{"id":14969271,"url":"https://github.com/cucumber/cucumber-android","last_synced_at":"2025-10-05T05:47:01.625Z","repository":{"id":33368849,"uuid":"139706740","full_name":"cucumber/cucumber-android","owner":"cucumber","description":"Android support for Cucumber-JVM","archived":false,"fork":false,"pushed_at":"2024-08-20T08:56:09.000Z","size":594,"stargazers_count":135,"open_issues_count":12,"forks_count":62,"subscribers_count":17,"default_branch":"main","last_synced_at":"2024-10-29T14:46:53.508Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cucumber.png","metadata":{"funding":{"open_collective":"cucumber","github":"cucumber"},"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-07-04T10:25:56.000Z","updated_at":"2024-09-10T15:23:23.000Z","dependencies_parsed_at":"2023-09-23T16:18:03.127Z","dependency_job_id":"f1c94373-f398-44ec-8ff4-10a279094217","html_url":"https://github.com/cucumber/cucumber-android","commit_stats":{"total_commits":312,"total_committers":26,"mean_commits":12.0,"dds":0.6955128205128205,"last_synced_commit":"0c08b28eefa4eb23fb60fb674b36e956931669bf"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cucumber%2Fcucumber-android","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cucumber%2Fcucumber-android/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cucumber%2Fcucumber-android/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cucumber%2Fcucumber-android/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cucumber","download_url":"https://codeload.github.com/cucumber/cucumber-android/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246188590,"owners_count":20737737,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-24T13:41:28.186Z","updated_at":"2025-10-05T05:47:01.534Z","avatar_url":"https://github.com/cucumber.png","language":"Kotlin","funding_links":["https://opencollective.com/cucumber","https://github.com/sponsors/cucumber"],"categories":[],"sub_categories":[],"readme":"[![Build](https://github.com/cucumber/cucumber-android/actions/workflows/build.yaml/badge.svg)](https://github.com/cucumber/cucumber-android/actions/workflows/build.yaml)\n\n# Cucumber-Android\n\nThis project implements Android support for Cucumber-JVM. It allows\nrunning cucumber tests with Android Test Orchestrator and using\nsharding. \n\nNOTE: Although minSdkVersion for `cucumber-android` is 14 it requires\nJava 8 language features and minimum Android API level 26. This is done\npurposely to allow using cucumber in apps with lower minSdk (to avoid\ncompile errors) but tests should be run on devices with API \u003e= 26. \nHowever with desugaring enabled it may work in some configurations on lower API levels assuming that desugaring covers all the Java 8 api.\nNot all features from `cucumber-jvm` are supported in `cucumber-android` due to differences in Android vs JDK (especially junit and html plugins which requires xml factory classes not available in Android)\n\n## Developers\n\n### Prerequisites\n\nThis is ordinary multimodule Android project\n\n* `cucumber-android` - main library\n* `cucumber-android-hilt` - Hilt object factory\n* `cucumber-junit-rules-support` - internal module for Junit rules support\n* `cukeulator` - sample application with instrumented tests\n\n### Building\n\n```sh\n./gradlew assemble\n```\n\n### Setting up the dependency\n\nThe first step is to include cucumber-android into your project, for example, as a Gradle androidTestImplementation dependency:\n\n```groovy\nandroidTestImplementation \"io.cucumber:cucumber-android:$cucumberVersion\"\n```\n\n### Using Cucumber-Android\n\n1. Create a class in your testApplicationId package (usually it's a `namespace` from `build.gradle` with `.test` suffix) and add `@CucumberOptions` annotation to that class. You can also put such class in different package or have many such classes in different packages but then you have to provide path to it in instrumentation argument `optionsAnnotationPackage`.\n\nGradle example:\n```groovy\nandroid {\n    defaultConfig {\n        testInstrumentationRunner \"io.cucumber.android.runner.CucumberAndroidJUnitRunner\"\n        testInstrumentationRunnerArguments(optionsAnnotationPackage: \"some.other.package\")\n    }\n}\n```\n\nCommandline example:\n```\nadb shell am instrument -w -e optionsAnnotationPackage some.other.package com.mycompany.app.test/com.mycompany.app.test.MyTests\n```\n\nThis class doesn't need to have anything in it, but you can also put some codes in it if you want. The purpose of doing this is to provide cucumber options. A simple example can be found in `cukeulator`. Or a more complicated example here:\n```java\npackage com.mycompany.app.test;\n\n@CucumberOptions(glue = { \"com.mytest.steps\" }, tags = \"~@wip\" , features = { \"features\" })\npublic class MyTests \n{\n}\n```\nglue is the list of packages which contain step definitions classes and also classes annotated with `@WithJunitRule`, tags is the tags placed above scenarios titles you want cucumber-android to run or not run, features is the path to the feature files in android test assets directory.\n\n2. Write your .feature files under your project's android test  `assets/\u003cfeatures-folder\u003e` folder. If you specify `features = \"features\"` in `@CucumberOptions` like the example above then it's `androidTest/assets/features` (might be also `androidTest\u003cFlavor/BuildType\u003e/assets/features`).\n\n3. Write your step definitions under the package name specified in glue. For example, if you specified `glue = [\"com.mytest.steps\"]`, then create a new package under your `androidTest/java` (or `androidTest/kotlin`) named `com.mytest.steps` and put your step definitions under it. Note that all subpackages will also be included, so you can also put in `com.mytest.steps.mycomponent`.\n\n4. Set instrumentation runner to `io.cucumber.android.runner.CucumberAndroidJUnitRunner` or class that extends it\n```groovy\nandroid.defaultConfig.testInstrumentationRunner \"io.cucumber.android.runner.CucumberAndroidJUnitRunner\"\n```\n\nIf needed you can specify some cucumber options using instrumentation arguments. Check available options in `io.cucumber.android.CucumberAndroidJUnitArguments.PublicArgs` class \n\nFor example to specify glue package use:\n```groovy\nandroid.defaultConfig.testInstrumentationRunnerArguments(glue: \"com.mytest.steps\")\n```\n\n### Debugging\nPlease read [the Android documentation on debugging](https://developer.android.com/tools/debugging/index.html).\n\n### Examples\n\nCurrently there is one example in subproject [cukeulator](https://github.com/cucumber/cucumber-android/tree/master/cukeulator)\n\nTo create a virtual device and start an [Android emulator](https://developer.android.com/tools/devices/index.html):\n\n```\n$ANDROID_HOME/tools/android avd\n```\n\n### Junit rules support\n\nExperimental support for Junit rules was added in version `4.9.0`.\nCucumber works differently than junit - you cannot just add rule to some steps class\nbecause during scenario execution many such steps classes can be instantiated.\nCucumber has its own Before/After mechanism. If you have just 1 steps class then this could work\nIf you have many steps classes then it is better to separate rule and `@Before/@After` hooks  \n from steps classes\n\nTo let Cucumber discover that particular class has rules add\n```\n@WithJunitRule\nclass ClassWithRules {\n    ...\n}\n```\n\nand put this class in glue package. Glue packages are specified in `@CucumberOptions` annotation, see [Using Cucumber-Android](#using-cucumber-android)\n\nYou can specify tag expression like `@WithJunitRule(\"@MyTag\")` to control for which scenarios this rule should be executed. See `compose.feature` and `ComposeRuleHolder` for example\n\n\n### Sharding and running with Android Test Orchestrator\n\n`CucumberAndroidJUnitRunner` works with Android Test Orchestrator and sharding because it reports tests and classes as feature names and scenario names like `My feature#My scenario` and is able to parse `-e class` argument from instrumentation. \nIt also supports multiple names in `-e class` argument separated by comma. This means that feature and scenario name cannot have comma in it's name because it is reserved for separating multiple names (only if you want to use Orchestrator or in general `class` argument, for other use cases comma is allowed).\n\n\n### Jetpack Compose rule\n\n```\n@WithJunitRule\nclass ComposeRuleHolder {\n\n    @get:Rule\n    val composeRule = createEmptyComposeRule()\n}\n```\n\nthen inject this object in steps, e.g.\n(can be also inject as `lateinit var` field (depending on injection framework used)\n\n```\nclass KotlinSteps(val composeRuleHolder: ComposeRuleHolder, val scenarioHolder: ActivityScenarioHolder):SemanticsNodeInteractionsProvider by composeRuleHolder.composeRule {\n\n    ...\n    \n    @Then(\"^\\\"([^\\\"]*)\\\" text is presented$\")\n    fun textIsPresented(arg0: String) {\n        onNodeWithText(arg0).assertIsDisplayed()\n    }\n}\n```\n\nCheck [Junit rules support](#junit-rules-support) for more information of adding classes with JUnit rules\n\n### Hilt\n\nThere are 2 solutions for using Hilt with Cucumber:\n\n##### 1. HiltObjectFactory\n\nAdd dependency:\n```groovy\nandroidTestImplementation \"io.cucumber:cucumber-android-hilt:$cucumberVersion\"\n```\n\nDon't use any other dependency with `ObjectFactory` like `cucumber-picocontainer`\n\n`HiltObjectFactory` will be automatically used as `ObjectFactory`.\n\nTo inject object managed by Hilt into steps or hook or any other class managed by Cucumber:\n\n```kotlin\n@HiltAndroidTest\nclass KotlinSteps(\n    val composeRuleHolder: ComposeRuleHolder,\n    val scenarioHolder: ActivityScenarioHolder\n):SemanticsNodeInteractionsProvider by composeRuleHolder.composeRule {\n\n    @Inject\n    lateinit var greetingService:GreetingService\n\n    @Then(\"I should see {string} on the display\")\n    fun I_should_see_s_on_the_display(s: String?) {\n       Espresso.onView(withId(R.id.txt_calc_display)).check(ViewAssertions.matches(ViewMatchers.withText(s)))\n    }\n\n}\n```\n\nSuch class:\n- must have `@HiltAndroidTest` annotation to let Hilt generate injecting code\n- can have Cucumber managed objects like hooks injected in constructor\n- can have Cucumber managed objects injected in fields but such objects have to be annotated with `@Singleton` annotation and constructor has to be annotated with `@Inject` annotation \n- can have Hilt managed objects injected using field injection or constructor\n- can have objects injected in base class\n\nAlso:\nafter each scenario Hilt will clear all objects and create new ones (even these marked as @Singleton) (like it does for each test class in Junit)\n\n##### 2. @WithJunitRule\n\n\nHilt requires to have rule in actual test class (which for cucumber is impossible\nbecause there is no such class). To workaround that:\n\nSee https://developer.android.com/training/dependency-injection/hilt-testing#multiple-testrules\nhow to use hilt with other rules (like compose rule)\n\n```\n@WithJunitRule(useAsTestClassInDescription = true)\n@HiltAndroidTest\nclass HiltRuleHolder {\n\n    @Rule(order = 0) \n    @JvmField\n    val hiltRule = HiltAndroidRule(this)\n\n   //if you need it to be injected   \n    @Inject\n    lateinit var greetingService: GreetingService\n\n    @Before\n    fun init() {\n        //if you have anything to inject here and/or used elsewhere in tests    \n        hiltRule.inject()\n    }\n\n}\n```\n\nthen you can inject such class to steps class using Cucumber dependency injector (like picocontainer) \n\n\n\n### Running scenarios from IDE\n\nThere is third-party plugin (not related with Cucumber organisation and this repository) which allows running scenarios directly from Android Studio or Intellij\n\n[Cucumber for Kotlin and Android](https://plugins.jetbrains.com/plugin/22107-cucumber-for-kotlin-and-android)\n\n\n## Troubleshooting\n\n1. Compose tests fails\n\n`java.lang.IllegalStateException: Test not setup properly. Use a ComposeTestRule in your test to be able to interact with composables`\n\n##### Solution\n\nCheck [Jetpack Compose rule](#jetpack-compose-rule) section. Make sure that your class with `@WithJunitRule` annotation is placed in glue package as described in [Using Cucumber-Android](#using-cucumber-android)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcucumber%2Fcucumber-android","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcucumber%2Fcucumber-android","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcucumber%2Fcucumber-android/lists"}