Skip to content

Commit 6be61a9

Browse files
author
temyers
committed
deprecate the plugin
1 parent 5f0bc5c commit 6be61a9

File tree

2 files changed

+282
-271
lines changed

2 files changed

+282
-271
lines changed

‎readme.md

Lines changed: 6 additions & 271 deletions
Original file line numberDiff line numberDiff line change
@@ -1,276 +1,11 @@
1-
cucumber-jvm-parallel-plugin ![CI status](https://travis-ci.org/temyers/cucumber-jvm-parallel-plugin.svg?branch=master)
2-
============================
1+
# cucumber-jvm-parallel-plugin
32

4-
A common approach for running Cucumber features in parallel is to create a suite of Cucumber runners, one for each suite of tests you wish to run in parallel. For maximum parallelism, there should be a runner per feature file.
3+
#STOP!
54

6-
This is a pain to maintain and not very DRY.
5+
Before reading further, you probably should not be using this plugin.
76

8-
This is where the cucumber-jvm-parallel-plugin comes in. This plugin automatically generates a Cucumber JUnit or TestNG runner for each scenario/feature file found in your project.
7+
As of `cucumber-jvm:4.0.0` parallel execution is supported natively by cucumber. As such, upgrading to Cucumber 4.0.0 is recommended and this plugin is no longer maintained.
98

10-
Note: As of `cucumber-jvm:4.0.0` parallel execution is supported natively by cucumber.
9+
# Legacy documentation
1110

12-
Quickstart
13-
----------
14-
15-
Place your feature files in `src/test/resources/features/`
16-
17-
Add the following to your POM file, updating the `<glue>` definition to point to your glue code packages:
18-
```xml
19-
<plugin>
20-
<groupId>com.github.temyers</groupId>
21-
<artifactId>cucumber-jvm-parallel-plugin</artifactId>
22-
<version>5.0.0</version>
23-
<executions>
24-
<execution>
25-
<id>generateRunners</id>
26-
<phase>generate-test-sources</phase>
27-
<goals>
28-
<goal>generateRunners</goal>
29-
</goals>
30-
<configuration>
31-
<!-- Mandatory -->
32-
<!-- List of package names to scan for glue code. -->
33-
<glue>
34-
<package>com.example</package>
35-
<package>com.example.other</package>
36-
</glue>
37-
</configuration>
38-
</execution>
39-
</executions>
40-
</plugin>
41-
```
42-
43-
Configure the [Maven Failsafe](http://maven.apache.org/surefire/maven-failsafe-plugin/) to execute your runners.
44-
45-
Generated JUnit test runners will be named `ParallelNIT.java`, where `N` is a one up number.
46-
Cucumber JSON reports will be output to: `target/cucumber-parallel`
47-
48-
Detailed Configuration
49-
----------------------
50-
51-
The following snippet details all the possible configuration options and example usage:
52-
Please refer to the integration tests for example usage:
53-
54-
```xml
55-
<plugin>
56-
<groupId>com.github.temyers</groupId>
57-
<artifactId>cucumber-jvm-parallel-plugin</artifactId>
58-
<version>5.0.0</version>
59-
<executions>
60-
<execution>
61-
<id>generateRunners</id>
62-
<phase>generate-test-sources</phase>
63-
<goals>
64-
<goal>generateRunners</goal>
65-
</goals>
66-
<configuration>
67-
<!-- Mandatory -->
68-
<!-- List of package names to scan for glue code. -->
69-
<glue>
70-
<package>com.example</package>
71-
<package>com.example.other</package>
72-
</glue>
73-
<!-- These are optional, with the default values -->
74-
<!-- Where to output the generated tests -->
75-
<outputDirectory>${project.build.directory}/generated-test-sources/cucumber</outputDirectory>
76-
<!-- The directory, which must be in the root of the runtime classpath, containing your feature files. -->
77-
<featuresDirectory>src/test/resources/features/</featuresDirectory>
78-
<!-- Directory where the cucumber report files shall be written -->
79-
<cucumberOutputDir>target/cucumber-parallel</cucumberOutputDir>
80-
<!-- List of cucumber plugins. When none are provided the json formatter is used. For more
81-
advanced usage see section about configuring cucumber plugins -->
82-
<plugins>
83-
<plugin>
84-
<name>json</name>
85-
</plugin>
86-
<plugin>
87-
<name>com.example.CustomHtmlFormatter</name>
88-
<extension>html</extension>
89-
</plugin>
90-
</plugins>
91-
<!-- CucumberOptions.strict property -->
92-
<strict>true</strict>
93-
<!-- CucumberOptions.monochrome property -->
94-
<monochrome>true</monochrome>
95-
<!-- The tags to run, maps to CucumberOptions.tags property. Default is no tags. -->
96-
<tags>
97-
<tag>@billing</tag>
98-
<tag>~@billing</tag>
99-
<tag>@important</tag>
100-
<tag>@important,@billing</tag>
101-
</tags>
102-
<!-- Generate TestNG runners instead of JUnit ones. -->
103-
<useTestNG>false</useTestNG>
104-
<!-- The naming scheme to use for the generated test classes. One of ['simple', 'feature-title', 'pattern'] -->
105-
<namingScheme>simple</namingScheme>
106-
<!-- The class naming pattern to use. Only required/used if naming scheme is 'pattern'.-->
107-
<namingPattern>Parallel{c}IT</namingPattern>
108-
<!-- One of [SCENARIO, FEATURE]. SCENARIO generates one runner per scenario. FEATURE generates a runner per feature. -->
109-
<parallelScheme>SCENARIO</parallelScheme>
110-
<!-- Specify a custom template for the generated sources (this is a path relative to the project base directory) -->
111-
<customVmTemplate>src/test/resources/cucumber-custom-runner.vm</customVmTemplate>
112-
<!-- Specify a custom package name for generated sources. Default is no package.-->
113-
<packageName>com.example</packageName>
114-
</configuration>
115-
</execution>
116-
</executions>
117-
</plugin>
118-
```
119-
120-
If `cucumber.options` VM argument is specified as per the [Cucumber CLI options](https://cucumber.io/docs/reference/jvm), they shall override the configuration tags.
121-
122-
Where glue is a comma separated list of package names to use for the Cucumber Glue.
123-
124-
The plugin will search `featuresDirectory` for `*.feature` files and generate a JUnit test for each one.
125-
> **WARNING:** `featuresDirectory` must denote a directory within the root of the classpath.
126-
> **Example:**
127-
> * Resources in `src/test/resources` are added to the classpath by default.
128-
> * `src/test/resources/features` **is** in the root of the classpath, so **would be valid** for `featuresDirectory`
129-
> * `src/test/resources/features/sub_folder` is **not** in the root of the classpath, so **would not be valid** to put in `featuresDirectory`
130-
131-
If you prefer to generate TestNG tests, set `useTestNG` to true
132-
133-
The Java source is generated in `outputDirectory`, based on the naming scheme used.
134-
135-
Each runner is configured to output the results to a separate output file under `target/cucumber-parallel`
136-
137-
### Cucumber Plugins ###
138-
139-
Cucumber plugins that write to a file are referenced using the syntax
140-
`name[:outputDirectory/excutorId[.extension]]`. Because not all plugins create output and the
141-
excutorId is provided at runtime some leg work is needed.
142-
143-
#### Build-in Cucumber Plugins ####
144-
145-
```xml
146-
<plugins>
147-
<plugin>
148-
<!--The available options are junit, testng, html, pretty, json, usage and rerun -->
149-
<name>json</name>
150-
<!--Optional file extension. For build in cucumber plugins a sensible default is provided. -->
151-
<extension>json</extension>
152-
<!--Optional output directory. Overrides cucumberOutputDirectory. Usefull when different
153-
plugins create files with the same extension-->
154-
<outputDirectory>${project.build.directory}/cucumber-parallel/json</outputDirectory>
155-
</plugin>
156-
</plugins>
157-
```
158-
159-
#### Custom Cucumber Plugins ####
160-
161-
```xml
162-
<plugins>
163-
<plugin>
164-
<name>path.to.my.formaters.CustomHtmlFormatter</name>
165-
<!--Optional file extension. Unless the formatter writes to a file it is strongly
166-
recommend that one is provided. -->
167-
<extension>html</extension>
168-
<!--Optional output directory. Overrides cucumberOutputDirectory. Useful when different
169-
plugins create files with the same extension-->
170-
<outputDirectory>${project.build.directory}/cucumber-parallel/html</outputDirectory>
171-
</plugin>
172-
</plugins>
173-
```
174-
175-
#### Custom Cucumber Plugins without output ####
176-
177-
```xml
178-
<plugins>
179-
<plugin>
180-
<name>path.to.my.formaters.NoOutputFormatter</name>
181-
<!--Set to true if this plug creates no output. Setting extension or outputDirectory
182-
will override this setting -->
183-
<noOutput>true</noOutput>
184-
</plugin>
185-
</plugins>
186-
```
187-
188-
### Naming Scheme ###
189-
190-
The naming scheme used for the generated files is controlled by the `namingScheme` property. The following values are supported:
191-
192-
| Property | Generated Name |
193-
| ------------- | -------------- |
194-
| simple | `ParallelXXIT.java`, where `XX` is a one up counter.|
195-
| feature-title | The name is generated based on the feature title with a set of rules to ensure it is a valid classname. The reules are detailed in the next subsection below. |
196-
| pattern | Generate the filename based on the `namingPattern` property.|
197-
198-
By default, generated test files use the `simple` naming strategy.
199-
200-
#### Feature-title Naming Scheme - rules ####
201-
202-
* Spaces are removed, camel-casing the title
203-
* If the feature file starts with a digit, the classname is prefixed with '_'
204-
* A one up counter is appended to the classname, to prevent clashes.
205-
206-
#### Pattern Naming Scheme - tokens ####
207-
208-
The following tokens can be used in the pattern:
209-
* `{f}` Converts the feature file name to a valid class name using the rules for feature-title, apart from the one up counter.
210-
* `{c}` Adds a one up counter.
211-
* `{c:n}` Adds a one up counter modulo n (useful for selecting tests for parallelisation).
212-
* By default counter value is zero padded to two characters and modulo counter is not padded at all. If you need a different zero padded length, this can be achieved by prefixing the character `c` by the length required - for example `{3c}` will yield `001` instead of `01`
213-
214-
#### Note on Pattern Naming Scheme ####
215-
The `pattern` naming scheme is for advanced usage only.
216-
217-
It is up to you to ensure that class names generated are valid and there are no clashes. If the same class name is generated multiple times, then it shall be overwritten and some of your tests will not be executed.
218-
219-
The `namingPattern` property is for the **class name** only. Do not add the `.java` suffix.
220-
221-
### Custom Templates ###
222-
223-
Some reporting plugins, such as
224-
[Cucumber Extent Reporter](https://github.com/email2vimalraj/CucumberExtentReporter), require some
225-
setup before a test is started. A template can be used to customize the integration tests. For a
226-
sample see the [extents-report](src/it/junit/extents-report) integration test. For a full list of
227-
available variables please see CucumberITGeneratorBy(Feature|Scenario).
228-
229-
FAQ
230-
===
231-
Q. Why are my tests not executed?
232-
233-
A. By default this plugin generates integration tests. Ensure that the
234-
[Maven Failsafe Plugin](https://maven.apache.org/surefire/maven-failsafe-plugin/) is properly
235-
configured.
236-
237-
Q. Why am I not seeing any generated runners?
238-
239-
A. Scenarios that don't match any tags are excluded. If there is no scenario to run, no runner will
240-
be generated.
241-
242-
Q. Is there a mailing list?
243-
244-
A. No. but we have a Gitter channel: https://gitter.im/cucumber-jvm-parallel-plugin/
245-
246-
Migration
247-
=========
248-
249-
Migrating from a previous version of the cucumber-jvm-parallel-plugin?
250-
251-
Please read the [Migration Notes](./migration.md).
252-
253-
254-
Changelog
255-
=========
256-
257-
* [Changelog](./changelog.md)
258-
259-
Contributing
260-
============
261-
262-
To contribute:
263-
264-
* Create an integration test to demonstrate the behaviour under `src/it/`. For example, to add support for multiple output formats for junit runners:
265-
* Create `src/it/junit/multiple-format`
266-
* copy the contents of the `src/it/junit/simple-it` directory and update the `pom/src` as appropriate to demonstrate the configuration. Update `verify.groovy` to implement the test for your feature.
267-
* Run `mvn clean install -Prun-its` to run the integration tests.
268-
* Implement the feature
269-
* When all tests are passing, submit a pull request.
270-
* Coding standards, based on the [Google Style Guide](https://github.com/google/styleguide) are enforced using Checkstyle. Formatters for Eclipse and IntelliJ are provided in the `doc/style` folder
271-
272-
Once the pull request has been merged, a new release will be performed as soon as practicable.
273-
274-
Release Process
275-
---------------
276-
See [Maven Central upload guide](https://maven.apache.org/guides/mini/guide-central-repository-upload.html)
11+
If you still want to read the documentation, see [readme_archive.md](readme_archive.md)

0 commit comments

Comments
 (0)