README.md
1# Flicker Test Library
2
3## Motivation
4This set of tests use the flickerlib from `platform_testing/libraries/flicker` to execute a set of common UI transitions to detect discontinuous or unpredictable behavior.
5
6The tests are organized in packages according to the transitions they test (e.g., `rotation`, `splitscreen`).
7
8## Adding a Test
9
10By default tests should inherit from `RotationTestBase` or `NonRotationTestBase` and must override the variable `transitionToRun` (Kotlin) or the function `getTransitionToRun()` (Java).
11Only tests that are not supported by these classes should inherit directly from the `FlickerTestBase` class.
12
13### Rotation animations and transitions
14
15Tests that rotate the device should inherit from `RotationTestBase`.
16Tests that inherit from the class automatically receive start and end rotation values.
17Moreover, these tests inherit the following checks:
18* all regions on the screen are covered
19* status bar is always visible
20* status bar rotates
21* nav bar is always visible
22* nav bar is rotates
23
24The default tests can be disabled by overriding the respective methods and including an `@Ignore` annotation.
25
26### Non-Rotation animations and transitions
27
28`NonRotationTestBase` was created to make it easier to write tests that do not involve rotation (e.g., `Pip`, `split screen` or `IME`).
29Tests that inherit from the class are automatically executed twice: once in portrait and once in landscape mode and the assertions are checked independently.
30Moreover, these tests inherit the following checks:
31* all regions on the screen are covered
32* status bar is always visible
33* nav bar is always visible
34
35The default tests can be disabled by overriding the respective methods and including an `@Ignore` annotation.
36
37### Exceptional cases
38
39Tests that rotate the device should inherit from `RotationTestBase`.
40This class allows the test to be freely configured and does not provide any assertions.
41
42
43### Example
44
45Start by defining common or error prone transitions using `TransitionRunner`.
46```kotlin
47@LargeTest
48@RunWith(Parameterized::class)
49@FixMethodOrder(MethodSorters.NAME_ASCENDING)
50class MyTest(
51 beginRotationName: String,
52 beginRotation: Int
53) : NonRotationTestBase(beginRotationName, beginRotation) {
54 init {
55 mTestApp = MyAppHelper(InstrumentationRegistry.getInstrumentation())
56 }
57
58 override val transitionToRun: TransitionRunner
59 get() = TransitionRunner.newBuilder()
60 .withTag("myTest")
61 .recordAllRuns()
62 .runBefore { device.pressHome() }
63 .runBefore { device.waitForIdle() }
64 .run { testApp.open() }
65 .runAfter{ testApp.exit() }
66 .repeat(2)
67 .includeJankyRuns()
68 .build()
69
70 @Test
71 fun myWMTest() {
72 checkResults {
73 WmTraceSubject.assertThat(it)
74 .showsAppWindow(MyTestApp)
75 .forAllEntries()
76 }
77 }
78
79 @Test
80 fun mySFTest() {
81 checkResults {
82 LayersTraceSubject.assertThat(it)
83 .showsLayer(MyTestApp)
84 .forAllEntries()
85 }
86 }
87}
88```
89