Cross-Library setup
This library provides support for running the very same screenshot tests for your Composables or Android Views across different libraries, without rewriting them!
I wrote about why you might need it and how AndroidUiTestingUtils supports this in these 2 blog posts:
Currently, it provides out-of-the-box support for the following screenshot testing libraries:
Out-of-the-box support for Facebook screenshot-tests-for-android and QuickBird Studios snappy is on the roadmap.
You can also add support for your own solution / another library in 2 steps by
Implementing
ScreenshotTestRuleForComposable
orScreenshotTestRuleForView
interfaces andUsing that implementation in
ScreenshotLibraryTestRuleForComposable
orScreenshotLibraryTestRuleForView
respectively, as we'll see below.
Basic configuration
This section covers the basics: how to configure cross-library screenshot tests that will run with one library, the one of your choice.
The main benefit is, that to switch to another library you won't need to rewrite any of these tests!
To choose the library the test run with dynamically and/or for shared screenshot tests (i.e. running either on-device or on JVM), continue reading the next section after this one.
You can achieve this in 4 easy steps:
Firstly, configure the screenshot testing library you want your tests to support, as if you'd write them with that specific library. Visit its respective Github page for more info. It's recommended to use the AndroidUiTestingUtils version that corresponds to the screenshot library version you're using:
2.6.0
1.32.2
1.3.5
0.4.1
6.1.0
3.2.0
2.5.0
1.26.0
1.3.4
0.4.1
6.1.0
3.2.0
2.4.0
1.26.0
1.3.3
0.4.1
6.1.0
3.2.0
2.3.2-2.3.5
1.12.0
1.3.3
0.4.1
6.1.0
2.0.0
2.3.1
1.11.0
1.3.3
0.4.1
6.1.0
2.0.0
2.3.0
1.10.1
1.3.3
0.4.1
6.1.0
2.0.0
2.2.x
1.8.0-alpha-6
1.3.2
0.4.1
6.0.0
2.0.0
2.1.0
1.8.0-alpha-6
1.3.1
0.4.1
6.0.0
2.0.0
2.0.1
1.7.0-rc-1
1.3.1
0.4.1
6.0.0
-
2.0.0
1.5.0-rc-1
1.3.1
0.4.1
6.0.0
-
AndroidUiTestingUtils 2.3.1+ uses Robolectric 4.12.1 under the hood, which adds support for Native Graphics on Windows, and therefore Roborazzi!
If having troubles with Paparazzi, beware of the release notes of 1.3.2
After that, include the following dependencies in the
build.gradle
of the module that will include your cross-library screenshot tests.
Create the corresponding
ScreenshotLibraryTestRuleForComposable
orScreenshotLibraryTestRuleForView
, for instance:
Executing your screenshot tests with another library will just require that you change the ScreenshotLibraryTestRule accordingly!
Finally, write your tests with that
MyLibraryScreenshotTestRule
. Put them under the corresponding folder, i.eunitTest
(e.g. Roborazzi & Paparazzi) orandroidTest
(e.g. Dropshots, Shot, Android-Testify). For an example, see this section.
Want to try it out? Check out these executable examples:
Roborazzi
If using Roborazzi or a Robolectric based library, enable robolectric native graphics through Gradle as well. Optionally, you can also enable hardware native graphics via Gradle to render shadows and elevation!
Hardware Native Graphics requires AndroidUiTestingUtils 2.3.1+, which use Robolectric 4.12.1 under the hood.
Android-Testify
If using Android-Testify, you also need to define the annotation it uses to identify screenshot tests in the Android-Testify gradle plugin as follows
Annotate your Cross-Library screenshot tests with it to run them with Android-Testify
Shared tests
These are tests that can run either on the JVM or on a device/emulator. For that, you have to share resources between Unit Tests and Android Tests.
The easiest way is to add this in the build.gradle
of the module where you'll write shared tests and then write your screenshot tests under src/sharedTest
,
Android Studio might show errors if sharedTests
are defined in an application module. Consider creating a separate library module for testing the UI of your application module.
Now follow steps 1. & 2. as in the Basic configuration section for each library. After that:
Create the corresponding
SharedScreenshotLibraryTestRuleForComposable
orSharedScreenshotLibraryTestRuleForView
, for instance:
Finally, write your tests with the
CrossLibraryScreenshotTestRule
. For an example, see this section. Put them under thesharedTest
folder we've just defined.
This is likely the most common use case. There are Ready-To-Run examples available
Pick the library dynamically
If you want to use
Many On-device libraries (e.g. either Shot, Dropshots or Android-Testify)
and/or
Many JVM libraries (e.g.. either Paparazzi or Roborazzi).
you need to dynamically pick the library your screenshot tests run with.
For that you'll need some extra configuration, for instance, a custom Gradle property that you can pass via command line e.g.
-PscreenshotLibrary=shot
Check these links for advice on how to configure the Gradle file and the SharedScreenshotTestRule
to get it working:
Last updated