Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/gradle/cucumber-companion
Maven & Gradle plugins providing convenient support for running Cucumber test directly from Maven/Gradle
https://github.com/gradle/cucumber-companion
cucumber gradle gradle-plugin maven maven-plugin
Last synced: 4 months ago
JSON representation
Maven & Gradle plugins providing convenient support for running Cucumber test directly from Maven/Gradle
- Host: GitHub
- URL: https://github.com/gradle/cucumber-companion
- Owner: gradle
- License: apache-2.0
- Created: 2023-08-30T09:54:59.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-09-24T14:00:42.000Z (4 months ago)
- Last Synced: 2024-09-26T12:41:02.548Z (4 months ago)
- Topics: cucumber, gradle, gradle-plugin, maven, maven-plugin
- Language: Groovy
- Homepage:
- Size: 562 KB
- Stars: 13
- Watchers: 16
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: Readme.adoc
- License: LICENSE
Awesome Lists containing this project
README
https://github.com/gradle/cucumber-companion/blob/main/LICENSE[image:https://img.shields.io/github/license/gradle/cucumber-companion[License]]
https://central.sonatype.com/artifact/com.gradle.cucumber.companion/cucumber-companion-maven-plugin[image:https://img.shields.io/maven-central/v/com.gradle.cucumber.companion/cucumber-companion-maven-plugin.svg?label=Maven%20Central[Maven Central]]
https://github.com/gradle/cucumber-companion/actions/workflows/verify.yml[image:https://github.com/gradle/cucumber-companion/actions/workflows/verify.yml/badge.svg?branch=main[GitHub Workflow Status]]
= Cucumber Companion
// Keep in sync with gradle.properties
:version: 1.1.0
// keep in sync with version catalog (libs.version.toml)
:minGradleVersion: 7.3
:minMavenVersion: 3.8.6
== Why would you add the Cucumber Companion plugin to your build?
Gradle and Maven (Surefire/Failsafe) support only class-based tests (https://github.com/gradle/gradle/issues/4773[gradle/#4773],
https://issues.apache.org/jira/browse/SUREFIRE-1724[SUREFIRE-1724]), which means that they can't discover cucumbers `*.feature` files as tests.
The https://github.com/cucumber/cucumber-jvm/blob/main/cucumber-junit-platform-engine/README.md#use-the-junit-platform-suite-engine[recommended workaround] is to create a single JUnit 5 suite class to run all the feature files.
This works fine, if your goal is to just always run all tests.
However, if you want to be able to run a single feature file or use advanced test acceleration techniques, such as https://docs.gradle.com/enterprise/predictive-test-selection/[Predictive Test Selection (PTS)], or https://docs.gradle.com/enterprise/test-distribution/[Test Distribution (TD)], then you need to have a single test class per feature file.
This is where the Cucumber Companion plugins come in: they automate the creation of the necessary JUnit 5 suite files to allow a fine-grained selection of tests.
We think of the generated JUnit 5 suite files as _companions_ to the respective Cucumber feature files.
Also, the plugins don't replace anything from Cucumber, but act as companions to it. Hence, we named the plugin _Cucumber Companion_.
== Installation and Usage
=== Prerequisites
This document assumes that you have followed the basic instructions from https://cucumber.io/docs/installation/java/ and https://github.com/cucumber/cucumber-jvm/tree/main/cucumber-junit-platform-engine to set up the necessary dependencies.
=== Gradle
The Cucumber Companion plugin requires _at least_ Gradle version {minGradleVersion}.
Add the plugin declaration to the plugins block in your `build.gradle(.kts)` file.
[source,kotlin,subs="attributes+"]
----
plugins {
id("com.gradle.cucumber.companion") version "{version}"
}
----
If your Cucumber feature files are in the standard `src/test/resources` folder, this is all you have to do.
The plugin adds a `testGenerateCucumberSuiteCompanion` task, which you can run manually to verify that the generation works.
==== Test Suites
If your build uses the https://docs.gradle.org/current/userguide/jvm_test_suite_plugin.html[JVM Test Suite Plugin], and your features are _not_ in the default test-suite, then you can enable the companion file generation for other test suites as follows:
`build.gradle.kts` (Kotlin)
[source,kotlin]
----
testing {
suites {
functionalTest {
generateCucumberSuiteCompanion(project)
}
}
}
----
`build.gradle` (Groovy)
[source,groovy]
----
testing {
suites {
functionalTest {
cucumberCompanion.generateCucumberSuiteCompanion(delegate)
}
}
}
----
The added companion task has the pattern of `GenerateCucumberSuiteCompanion`, so for a suite named `functionalTest` it would be `functionalTestGenerateCucumberSuiteCompanion`.
However, there's usually no need to call it manually since the `compileJava` task depends on it.
==== Disabling generation for the default `test` task/suite
If you need to disable the generation of companion files for the default `test` task/suite, then you can do so via the `cucumberCompanion` extension.
`build.gradle.kts` (Kotlin)
[source,kotlin]
----
cucumberCompanion {
enableForStandardTestTask.set(false)
}
----
`build.gradle` (Groovy)
[source,groovy]
----
cucumberCompanion {
enableForStandardTestTask = false
}
----
==== Generation of companions not failing if there are no tests
This is interesting especially for test cases retries when all but few tests being filtered out.
It adds `failIfNoTests = false` to the generated `@Suite` annotation.
By default, companions execution will fail if all tests of a suite have been filtered out
in the JUnit5 `discovery` phase.
See also https://github.com/gradle/test-retry-gradle-plugin[Test Retry Gradle Plugin].
`build.gradle.kts` (Kotlin)
[source,kotlin]
----
cucumberCompanion {
allowEmptySuites.set(true)
}
----
`build.gradle` (Groovy)
[source,groovy]
----
cucumberCompanion {
allowEmptySuites = true
}
----
For the same outcome at the test suite level, define:
`build.gradle.kts` (Kotlin)
[source,kotlin]
----
testing {
suites {
functionalTest {
generateCucumberSuiteCompanion(project) {
allowEmptySuites.set(true)
}
}
}
}
----
`build.gradle` (Groovy)
[source,groovy]
----
testing {
suites {
functionalTest {
cucumberCompanion.generateCucumberSuiteCompanion(delegate) {
allowEmptySuites = true
}
}
}
}
----
_Note that_ the configuration of a test suite will have higher priority than plugin-level configuration.
=== Maven
The plugin has been tested with Maven versions >= {minMavenVersion}.
Add this plugin declaration to your `pom.xml`.
The goal is bound to the `generate-test-sources` lifecycle phase.
[source,xml,subs="attributes+"]
----
com.gradle.cucumber.companion
cucumber-companion-maven-plugin
{version}
generate-cucumber-companion-files
----
By default, the plugin generates `*Test.java` files for Surefire.
If you prefer to run your tests with Failsafe instead, then you can configure the plugin to use `IT` as suffix instead.
[source,xml,subs="attributes+"]
----
com.gradle.cucumber.companion
cucumber-companion-maven-plugin
{version}
generate-cucumber-companion-files
IT
----
==== Generation of companions not failing if there are no tests
This is interesting especially for test cases retries when all but few tests being filtered out.
It adds `failIfNoTests = false` to the generated `@Suite` annotation.
By default, companions execution will fail if all tests of a suite have been filtered out
in the JUnit5 `discovery` phase.
[source,xml,subs="attributes+"]
----
com.gradle.cucumber.companion
cucumber-companion-maven-plugin
{version}
generate-cucumber-companion-files
true
----