WebdriverIO Re-run Service

!Unit Test Coverage
!E2E Tests
!npm
!npm downloads
!node
!TypeScript
!Zero Dependencies
!License

This service tracks failing Mocha or Jasmine tests and Cucumber scenarios executed within the WebdriverIO test framework. It will allow failing or unstable tests or scenarios to be re-run.

Features

- 🔄 Re-run failed Mocha, Jasmine, or Cucumber tests after the main test run completes
- 🥒 Full Cucumber support including scenarios inside Rule: blocks
- 🏷️ Filter out scenarios with specific tags from re-runs
- 🪟 Cross-platform support (generates rerun.sh on Unix, rerun.bat on Windows)
- ⚙️ Configurable command prefix and custom parameters

Quality & Reliability

- ✅ 100% test coverage — comprehensive unit and E2E tests
- 🧪 E2E tests — real WebdriverIO runs across Cucumber, Mocha, and Jasmine
- 🖥️ Cross-platform CI — tested on macOS, Windows, and Linux
- 📦 Zero dependencies — only WebdriverIO peer dependencies, minimal footprint
- 🔷 100% TypeScript — fully typed for great IDE support
- 🚀 Modern Node.js — uses native APIs (crypto.randomUUID, util.parseArgs)

Compatibility

| wdio-rerun-service | WebdriverIO | Node.js |
|--------------------|-------------|---------|
| ^3.0.0 | ^8.0.0 \|\| ^9.0.0 | >=20 |
| ^2.1.0 | ^8.0.0 \|\| ^9.0.0 | >=18 |
| ^2.0.0 | ^8.0.0 | >=18 |
| ^1.7.0 | ^7.0.0 | >=14 |

Re-run vs. Retry

The retry logic built into WebdriverIO for Cucumber and Mocha/Jasmine is helpful for handling flaky steps in Cucumber and Mocha/Jasmine. Retrying in each framework has caveats:

- Cucumber: It does not take into account that some steps may not be able to be retried in the middle of a test. Running a step twice may break the rest of the Scenario or it may not be possible in the test context.
- Mocha/Jasmine: The retry logic may be applied to an individual test, however, this is still done in real-time and perhaps does not account for temporal issues or network connectivity problems.

The main distinctions of the re-run:

- Will re-run an entire individual Cucumber Scenario and not just a single step
- Enables an entire spec file to be re-run after a main test execution is complete
- May be copied and executed locally (retry cannot)
- Can still be used in conjunction with retry methods
- Does not require any code change to apply retry logic to flaky or problematic tests

It is recommended to take some time to evaluate the options available. A hybrid solution may be the best solution to provide the best real and actionable test results.

Installation

Using npm:

``bash
npm install wdio-rerun-service
`

Using yarn:

`bash
yarn add wdio-rerun-service
`

Using pnpm:

`bash
pnpm add wdio-rerun-service
`

After package installation is complete, add it to services array in wdio.conf.js:

`js
// wdio.conf.js
import RerunService from 'wdio-rerun-service';
export const config = {
// ...
services: [
[RerunService, {
// Re-run service options here...
}]
],
// ...
};
`

Instructions on how to install WebdriverIO can be found in the official documentation.

Usage

By design, this service does not automatically re-run failed tests.

After WebdriverIO has completed execution, if failures are found, a re-run script will be generated at rerunScriptPath (default: ./rerun.sh on Unix, ./rerun.bat on Windows).

You can then execute this script manually or integrate it into your CI pipeline.

$3

Set the environment variable DISABLE_RERUN=true to disable the service (useful during re-run execution to prevent infinite loops).

$3

Every team's re-run needs will differ—execution could be based on any number of factors. This is an example of how to accomplish a conditional re-run based on number of failures.

#### attemptRerun.sh

Executes ./rerun.sh if less than 25 failures have been found in the last execution of WebdriverIO.

`sh
#!/usr/bin/env bash
MAX_TO_RERUN=${MAX_TO_RERUN:=25}
if [ -f "rerun.sh" ]; then
echo "[rerun.sh] file exists, checking total failures."
NUMBER_OF_FAILURES=$(grep "\-\-spec" -o rerun.sh | wc -l | xargs)
if [ "$MAX_TO_RERUN" -gt "$NUMBER_OF_FAILURES" ]; then
echo "Re-running $NUMBER_OF_FAILURES failed scenarios!"
. ./rerun.sh
else
echo "Skipping re-run, expected < $MAX_TO_RERUN failures."
echo "Got $NUMBER_OF_FAILURES failures."
fi
else
echo "No [rerun.sh] file exists, skipping re-run!"
fi
`

#### Bash Re-run Command

Execute in shell:

`sh
. ./attemptRerun.sh
`

#### Integrate with NPM

Add task in package.json:

`json
"attempt-rerun": ". ./attemptRerun.sh"
`

#### NPM Re-run Command

Execute in shell:

`sh
npm run attempt-rerun
`

Configuration

The following options may be added to the wdio.conf.js file. To define options for the service you need to add the service to the services list in the following way:

`js
// wdio.conf.js
import RerunService from 'wdio-rerun-service';
export const config = {
// ...
services: [
[RerunService, {
// Re-run service options here...
}]
],
// ...
};
`

$3

Directory where all the re-run JSON data will be kept during execution.

Type: String

Default: ./results/rerun

Example:

`js
import RerunService from 'wdio-rerun-service';
export const config = {
// ...
services: [
[RerunService, {
rerunDataDir: './custom-rerun-directory'
}]
],
// ...
}
`

$3

Path to write the re-run script.

Type: String

Default: ./rerun.sh (Unix) or ./rerun.bat (Windows)

Example:

`js
import RerunService from 'wdio-rerun-service';
export const config = {
// ...
services: [
[RerunService, {
rerunScriptPath: './custom-path-for-rerun.sh'
}]
],
// ...
}
`

$3

(Cucumber-only) Set of Cucumber tags to exclude. If scenario contains a tag, the re-run service will skip analysis.

Type: Array

Default: []

Example:

`js
import RerunService from 'wdio-rerun-service';
export const config = {
// ...
services: [
[RerunService, {
ignoredTags: ['@known_bug']
}]
],
// ...
}
`

$3

Prefix which will be added to the re-run command that is generated.

Type: String

Default: ''

Example:

`js
import RerunService from 'wdio-rerun-service';
export const config = {
// ...
services: [
[RerunService, {
commandPrefix: "VARIABLE=true"
}]
],
// ...
}
`

$3

Parameters which will be added to the re-run command that is generated.
Can be used with commandPrefix.

Type: String

Default: ''

Example:

`js
import RerunService from 'wdio-rerun-service';
export const config = {
// ...
services: [
[RerunService, {
customParameters: "--foobar"
}]
],
// ...
}
`

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

`bash


Clone the repo

git clone https://github.com/webdriverio-community/wdio-rerun-service.git

Install dependencies

pnpm install

Run tests

pnpm test
``

License

MIT