From f21327270d04dbd54be973528b6c48f7ee39e9c3 Mon Sep 17 00:00:00 2001 From: Ruben Sousa Date: Mon, 30 Sep 2024 00:22:14 +0200 Subject: [PATCH 1/2] Move allure plugin to parent project directory --- build-logic/settings.gradle.kts | 2 +- .../.gitignore | 0 .../build.gradle | 0 .../gradle.properties | 0 .../allure/gradle/AllureReportGenerator.kt | 0 .../android/allure/gradle/AllureReportPlugin.kt | 0 .../android/allure/gradle/AllureTestReport.kt | 0 .../android/allure/gradle/LogcatFileFinder.kt | 0 .../plugin/android/allure/ExampleUnitTest.kt | 16 ---------------- settings.gradle.kts | 2 +- 10 files changed, 2 insertions(+), 18 deletions(-) rename {carioca-report/report-android-allure-gradle-plugin => carioca-report-allure-gradle-plugin}/.gitignore (100%) rename {carioca-report/report-android-allure-gradle-plugin => carioca-report-allure-gradle-plugin}/build.gradle (100%) rename {carioca-report/report-android-allure-gradle-plugin => carioca-report-allure-gradle-plugin}/gradle.properties (100%) rename {carioca-report/report-android-allure-gradle-plugin => carioca-report-allure-gradle-plugin}/src/main/kotlin/com/rubensousa/carioca/report/android/allure/gradle/AllureReportGenerator.kt (100%) rename {carioca-report/report-android-allure-gradle-plugin => carioca-report-allure-gradle-plugin}/src/main/kotlin/com/rubensousa/carioca/report/android/allure/gradle/AllureReportPlugin.kt (100%) rename {carioca-report/report-android-allure-gradle-plugin => carioca-report-allure-gradle-plugin}/src/main/kotlin/com/rubensousa/carioca/report/android/allure/gradle/AllureTestReport.kt (100%) rename {carioca-report/report-android-allure-gradle-plugin => carioca-report-allure-gradle-plugin}/src/main/kotlin/com/rubensousa/carioca/report/android/allure/gradle/LogcatFileFinder.kt (100%) delete mode 100644 carioca-report/report-android-allure-gradle-plugin/src/test/java/com/rubensousa/carioca/plugin/android/allure/ExampleUnitTest.kt diff --git a/build-logic/settings.gradle.kts b/build-logic/settings.gradle.kts index 3c28d744..48dae67c 100644 --- a/build-logic/settings.gradle.kts +++ b/build-logic/settings.gradle.kts @@ -14,4 +14,4 @@ dependencyResolutionManagement { rootProject.name = "build-logic" include(":allure-gradle-plugin") -project(":allure-gradle-plugin").projectDir = File("../carioca-report/report-android-allure-gradle-plugin") \ No newline at end of file +project(":allure-gradle-plugin").projectDir = File("../carioca-report-allure-gradle-plugin") \ No newline at end of file diff --git a/carioca-report/report-android-allure-gradle-plugin/.gitignore b/carioca-report-allure-gradle-plugin/.gitignore similarity index 100% rename from carioca-report/report-android-allure-gradle-plugin/.gitignore rename to carioca-report-allure-gradle-plugin/.gitignore diff --git a/carioca-report/report-android-allure-gradle-plugin/build.gradle b/carioca-report-allure-gradle-plugin/build.gradle similarity index 100% rename from carioca-report/report-android-allure-gradle-plugin/build.gradle rename to carioca-report-allure-gradle-plugin/build.gradle diff --git a/carioca-report/report-android-allure-gradle-plugin/gradle.properties b/carioca-report-allure-gradle-plugin/gradle.properties similarity index 100% rename from carioca-report/report-android-allure-gradle-plugin/gradle.properties rename to carioca-report-allure-gradle-plugin/gradle.properties diff --git a/carioca-report/report-android-allure-gradle-plugin/src/main/kotlin/com/rubensousa/carioca/report/android/allure/gradle/AllureReportGenerator.kt b/carioca-report-allure-gradle-plugin/src/main/kotlin/com/rubensousa/carioca/report/android/allure/gradle/AllureReportGenerator.kt similarity index 100% rename from carioca-report/report-android-allure-gradle-plugin/src/main/kotlin/com/rubensousa/carioca/report/android/allure/gradle/AllureReportGenerator.kt rename to carioca-report-allure-gradle-plugin/src/main/kotlin/com/rubensousa/carioca/report/android/allure/gradle/AllureReportGenerator.kt diff --git a/carioca-report/report-android-allure-gradle-plugin/src/main/kotlin/com/rubensousa/carioca/report/android/allure/gradle/AllureReportPlugin.kt b/carioca-report-allure-gradle-plugin/src/main/kotlin/com/rubensousa/carioca/report/android/allure/gradle/AllureReportPlugin.kt similarity index 100% rename from carioca-report/report-android-allure-gradle-plugin/src/main/kotlin/com/rubensousa/carioca/report/android/allure/gradle/AllureReportPlugin.kt rename to carioca-report-allure-gradle-plugin/src/main/kotlin/com/rubensousa/carioca/report/android/allure/gradle/AllureReportPlugin.kt diff --git a/carioca-report/report-android-allure-gradle-plugin/src/main/kotlin/com/rubensousa/carioca/report/android/allure/gradle/AllureTestReport.kt b/carioca-report-allure-gradle-plugin/src/main/kotlin/com/rubensousa/carioca/report/android/allure/gradle/AllureTestReport.kt similarity index 100% rename from carioca-report/report-android-allure-gradle-plugin/src/main/kotlin/com/rubensousa/carioca/report/android/allure/gradle/AllureTestReport.kt rename to carioca-report-allure-gradle-plugin/src/main/kotlin/com/rubensousa/carioca/report/android/allure/gradle/AllureTestReport.kt diff --git a/carioca-report/report-android-allure-gradle-plugin/src/main/kotlin/com/rubensousa/carioca/report/android/allure/gradle/LogcatFileFinder.kt b/carioca-report-allure-gradle-plugin/src/main/kotlin/com/rubensousa/carioca/report/android/allure/gradle/LogcatFileFinder.kt similarity index 100% rename from carioca-report/report-android-allure-gradle-plugin/src/main/kotlin/com/rubensousa/carioca/report/android/allure/gradle/LogcatFileFinder.kt rename to carioca-report-allure-gradle-plugin/src/main/kotlin/com/rubensousa/carioca/report/android/allure/gradle/LogcatFileFinder.kt diff --git a/carioca-report/report-android-allure-gradle-plugin/src/test/java/com/rubensousa/carioca/plugin/android/allure/ExampleUnitTest.kt b/carioca-report/report-android-allure-gradle-plugin/src/test/java/com/rubensousa/carioca/plugin/android/allure/ExampleUnitTest.kt deleted file mode 100644 index 645e9b97..00000000 --- a/carioca-report/report-android-allure-gradle-plugin/src/test/java/com/rubensousa/carioca/plugin/android/allure/ExampleUnitTest.kt +++ /dev/null @@ -1,16 +0,0 @@ -package com.rubensousa.carioca.plugin.android.allure - -import org.junit.Assert.assertEquals -import org.junit.Test - -/** - * Example local unit test, which will execute on the development machine (host). - * - * See [testing documentation](http://d.android.com/tools/testing). - */ -class ExampleUnitTest { - @Test - fun addition_isCorrect() { - assertEquals(4, 2 + 2) - } -} \ No newline at end of file diff --git a/settings.gradle.kts b/settings.gradle.kts index 8e1373ba..d7a56500 100644 --- a/settings.gradle.kts +++ b/settings.gradle.kts @@ -48,7 +48,7 @@ include(":carioca-hilt:carioca-hilt-runner") include(":carioca-junit4-rules") include(":carioca-report:report-junit4") include(":carioca-report:report-android") -include(":carioca-report:report-android-allure-gradle-plugin") +include(":carioca-report-allure-gradle-plugin") include(":carioca-report:report-android-coroutines") include(":carioca-report:report-runtime") include(":carioca-report:report-json") From ebbd6bf5af5d66ee7c0404670984c9c41ce2a94f Mon Sep 17 00:00:00 2001 From: Ruben Sousa Date: Mon, 30 Sep 2024 00:40:30 +0200 Subject: [PATCH 2/2] Update docs for new version --- docs/changelog/reports.md | 17 +++++++++ docs/index.md | 35 +++++++----------- docs/test-reports-android.md | 71 ++++++++++++++++-------------------- 3 files changed, 62 insertions(+), 61 deletions(-) diff --git a/docs/changelog/reports.md b/docs/changelog/reports.md index a164f1d5..aff38029 100644 --- a/docs/changelog/reports.md +++ b/docs/changelog/reports.md @@ -10,6 +10,23 @@ Libraries with the same version: ## Version 1.0.0 +### 1.0.0-alpha03 + +2024-09-30 + +#### API changes + +- Removed `dumpOnSuccess` from `DumpViewHierarchyInterceptor` + +#### Improvements + +- Decreased default delays for screen recordings, which decreases the total test execution time by around 25% [#63](https://github.com/rubensousa/Carioca/pull/63) +- Added `RecordingOrientation` to `RecordingOptions` to allow overriding the default orientation of the video [#65](https://github.com/rubensousa/Carioca/pull/65) + +#### Bug fixes + +- Fixed screenshot options inside steps or scenarios not using the provided options [#62](https://github.com/rubensousa/Carioca/pull/62) + ### 1.0.0-alpha02 2024-09-27 diff --git a/docs/index.md b/docs/index.md index 5428b544..9ed45ef0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,8 +2,18 @@ A collection of testing tools for Android that include flexible reporting capabilities -Artifacts available for test reports: +Motivation for these libraries: +1. I kept copying some of these classes around in multiple projects +2. Analysing the standard junit test reports when you have long UI tests gets frustrating +3. Consistent screen recording and screenshots across different screen resolutions +4. Flexible APIs for any test report format +5. No enforced inheritance in test classes unlike other testing libraries + + +Libraries currently available: + +1. [Instrumented test reports](test-reports-android.md) and [Allure Plugin](android-allure-plugin.md) ```groovy // Test reports for android tests androidTestImplementation "com.rubensousa.carioca:report-android:{{ report.version }}" @@ -15,9 +25,7 @@ androidTestImplementation "com.rubensousa.carioca:report-android-coroutines:{{ r androidTestImplementation "com.rubensousa.carioca:report-json:{{ report.version }}" androidTestImplementation "com.rubensousa.carioca:report-runtime:{{ report.version }}" ``` - -Artifacts available for hilt tests: - +2. [Instrumented tests with Hilt](hilt.md) ```groovy // Contains HiltFragmentScenario androidTestImplementation "com.rubensousa.carioca:hilt-fragment:{{ hilt.version }}" @@ -32,26 +40,11 @@ debugImplementation "com.rubensousa.carioca:hilt-manifest:{{ hilt.version }}" // Optional: default HiltTestRunner if you don't have your own androidTestImplementation "com.rubensousa.carioca:hilt-runner:{{ hilt.version }}" ``` - -Other artifacts: - +3. Junit4 rules ```groovy -// Contains RepeatTest and RetryTest -implementation "com.rubensousa.carioca:junit4-rules:{{ junit4_rules.version }}" +testImplementation "com.rubensousa.carioca:junit4-rules:{{ junit4_rules.version }}" ``` -Jump to [this guide](test-reports-android.md) for how to integrate this library. - - -Motivation for this library: - -1. I kept copying some of these classes around in multiple projects -2. Analysing the standard junit test reports when you have long UI tests gets frustrating -3. Consistent screen recording and screenshots across different screen resolutions -4. Flexible APIs for any test report format -5. No enforced inheritance in test classes unlike other testing libraries - - ## License Copyright 2024 Rúben Sousa diff --git a/docs/test-reports-android.md b/docs/test-reports-android.md index 326bb115..78cdf139 100644 --- a/docs/test-reports-android.md +++ b/docs/test-reports-android.md @@ -33,7 +33,7 @@ class SampleTest { !!! note Use different orders for your rules in case you have multiple of them and assign the lowest value to `TestReportRule`. This ensures that it starts before all other rules you have in your test suite. - Example: `@get:Rule(order = Int.MIN_VALUE)` + Example: `@get:Rule(order = 0)` for the report rule and `order = 1` for the next rule This basic setup will achieve this out of the box: @@ -41,6 +41,15 @@ This basic setup will achieve this out of the box: 2. Automatic screenshot when the test fails 3. Automatic dumps of the view hierarchy if the test fails +## Visualize reports + +The test reports are generated automatically after running any task like `connectedDebugAndroidTest` +and can be found in `build/outputs/connected_android_test_additional_output/**/carioca-report`. + +By default, those reports are in json format and are not really easily readable. +To visualize them properly, this library ships with an [Allure](https://allurereport.org/) plugin that can be used to generate test reports based on +the metadata collected through each test execution. Check it out in [this page](android-allure-plugin.md). + ## Test structure @@ -48,7 +57,7 @@ This basic setup will achieve this out of the box: You can decorate your tests with individual reports for every execution step: -```kotlin +```kotlin linenums="1" @Test fun testHomeIsDisplayedAfterQuickSettings() = report { @@ -71,7 +80,7 @@ fun testHomeIsDisplayedAfterQuickSettings() = report { Optionally, `Given`, `When`, `Then` statements from BDD are also available to describe your tests: -```kotlin +```kotlin linenums="1" @Test fun testHomeIsDisplayedAfterQuickSettings() = report { @@ -96,7 +105,7 @@ fun testHomeIsDisplayedAfterQuickSettings() = report { If you have re-usable logic in `@Before` or `@After` that you want to include in your reports, just use the following APIs: -```kotlin +```kotlin linenums="1" @Before fun before() = report.before { step("Press home") { @@ -119,7 +128,7 @@ fun after() = report.after { The library includes an `InstrumentedScenario` which allows you to re-use a set of steps across multiple tests: -```kotlin +```kotlin linenums="1" class ClickNotification : InstrumentedScenario("Click Notification") { private val device = UiDevice.getInstance( @@ -152,7 +161,7 @@ class ClickNotification : InstrumentedScenario("Click Notification") { Then, in your tests, can use it like so: -```kotlin +```kotlin linenums="1" hl_lines="9" @Test fun testAppOpensHomeAfterClickingNotification() = report { @@ -170,11 +179,11 @@ fun testAppOpensHomeAfterClickingNotification() = report { } ``` -## Test descriptions +### Extra metadata Using `@TestReport` allows you to describe your tests in more detail: -```kotlin +```kotlin linenums="1" @TestReport( id = "TicketID", title = "App opens home after notification click", @@ -187,18 +196,7 @@ Using `@TestReport` allows you to describe your tests in more detail: ) @Test fun testAppOpensHomeAfterClickingNotification() = report { - - step("Trigger notification") { - sendNotificationIntent() - } - - // Or When(ClickNotification()) - scenario(ClickNotification()) - - step("Home screen is visible") { - assertHomeScreenDisplayed() - } - + // Test body } ``` @@ -206,23 +204,27 @@ fun testAppOpensHomeAfterClickingNotification() = report { To override the recording options for individual tests, use `@TestRecording`: -```kotlin +```kotlin linenums="1" +// Disables screen recording for this test only @TestRecording( - scale = 1.0f, - keepOnSuccess = true, + enabled = false ) @Test -fun testSomething() { +fun fastTestThatShouldFinishInLessThan1Second() { } ``` -```kotlin -// Disables screen recording for this test only +Or also: + +```kotlin linenums="1" +// Records this test in landscape mode +// and keeps the recording file even if the test passes @TestRecording( - enabled = false + keepOnSuccess = true, + orientation = RecordingOrientation.LANDSCAPE ) @Test -fun fastTestThatShouldFinishInLessThan1Second() { +fun testInLandscape() { } ``` @@ -233,7 +235,7 @@ This configuration will replace the `RecordingOptions` from `InstrumentedReportR To override the screenshot options for individual tests, use `@TestScreenshot`: -```kotlin +```kotlin linenums="1" @TestScreenshot( scale = 1.0f, format = Bitmap.CompressFormat.PNG, @@ -244,14 +246,3 @@ fun testSomething() { ``` This configuration will replace the `ScreenshotOptions` from `InstrumentedReportRule` - -## Test reports - -The test reports are generated automatically after running any task like `connectedDebugAndroidTest` -and can be found in `build/outputs/connected_android_test_additional_output/**/carioca-report`. - -By default, those reports are in json format and are not really easily readable. -To visualize them properly, this library ships with an [Allure](https://allurereport.org/) plugin that can be used to generate test reports based on -the metadata collected through each test execution. Check it out in [this page](android-allure-plugin.md). - -