Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 37 ยท Reporting and CI

Running Scenarios in Parallel

Run Cucumber scenarios in parallel: JUnit Platform settings, thread-safe state, ThreadLocal drivers, shared data and resource locks, Cucumber.js and Ruby options.

A suite of 600 scenarios at three seconds each takes half an hour when run one after another. Run them on eight threads and it takes about four minutes. Parallel execution is the cheapest speed-up a suite can get, but it works only if scenarios are truly independent. Scenarios that share a database row, a static field or a single browser will start to fail in ways that disappear when you rerun them alone.

This lesson explains how to switch parallelism on, what must be thread-safe, and how to handle the few resources that cannot be shared. Cucumber cannot run here, so configuration is read-only; the runnable examples are Java thread demos that show the typical race condition and the fixes.

Turning it on (JUnit Platform engine)

In src/test/resources/junit-platform.properties:

PROPERTIES
cucumber.execution.parallel.enabled=true
cucumber.execution.parallel.config.strategy=fixed
cucumber.execution.parallel.config.fixed.parallelism=4
cucumber.execution.parallel.config.fixed.max-pool-size=4

Strategy dynamic instead sizes the pool from the number of CPU cores, scaled by cucumber.execution.parallel.config.dynamic.factor (default 1.0). With the JUnit engine, scenarios are the unit of parallelism, so one big feature can be spread over all threads.

Other runners:

Runner How
Cucumber-JVM with TestNG @DataProvider(parallel = true) on the provider method, thread count in testng.xml
Cucumber.js --parallel 4 (separate worker processes, so no shared memory)
Ruby the parallel_tests gem (parallel_cucumber), also separate processes

Process-based runners (Cucumber.js, Ruby) cannot share in-memory state by accident, which is easier to reason about. Thread-based runners (JVM) need more care.

What goes wrong

The big four:

  1. Static or global mutable state: two scenarios write the same field.
  2. A shared browser: two threads click in the same window.
  3. Shared data: two scenarios create [email protected] or edit the same row.
  4. Shared ports and files: both start a server on 8080 or write output.txt.

The first is easy to see in miniature. Four threads each add 1000 to a counter; a plain int loses updates because count++ is read, add, write, and threads interleave.

Java Shared state versus per-thread state (Java)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The plain counter usually loses updates, and which updates it loses changes on every run. Real tests that share mutable state fail in exactly this pattern: rarely, randomly, and never while you debug.

Making glue code thread-safe

  • Per-scenario objects through dependency injection (Scenario state): each scenario has its own world, so nothing is shared. This is the main fix.
  • One browser per scenario from a holder object or a ThreadLocal<WebDriver> (Selenium setup).
  • Unique data per scenario with generated keys and builders (Test data).
  • Ports and files: use port 0 (the OS chooses a free port) and temporary directories named per scenario.
  • Immutable shared data: constants loaded in @BeforeAll are fine if nobody changes them.
  • Thread-safe utilities: SimpleDateFormat is not thread-safe; use DateTimeFormatter. Counters need AtomicInteger.

When something cannot be shared

Some resources are single by nature: one test payment account, one shared sandbox, one hardware device. Cucumber's JUnit Platform engine lets you mark such scenarios with tags that map to JUnit's locking:

GHERKIN
@ResourceLock("sandbox-account")
Scenario: Refund a payment
  ...

@Isolated
Scenario: Reset the whole catalog
  ...

Scenarios with the same @ResourceLock name run one at a time, and an @Isolated scenario runs alone while everything else waits. Use them rarely: every lock reduces the speed-up, and a suite full of locks is telling you the data design needs work.

The stand-in below shows the lock idea with a ReentrantLock per named resource.

Java Named resource locks (Java stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Rolling out parallelism safely

  1. Run the suite sequentially and make it green and stable first.
  2. Turn on 2 threads, run it several times, and fix every failure that appears only in parallel.
  3. Increase threads while watching total time. Beyond the number of CPU cores (or the capacity of your grid or test database) there is no gain.
  4. Look at the timeline plugin report (Reports) to see whether one slow feature or a lock serializes the run.
  5. On CI, combine with sharding: split the scenario list across several machines as well (see CI pipelines).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which is the most important fix for glue code that fails only in parallel?

    Shared mutable state is the root cause. Give each scenario its own objects, driver and data.
  2. 2. In the JUnit Platform engine, what is the default unit of parallelism?

    Scenarios are scheduled across threads, so a large feature can be split.
  3. 3. What does an @Isolated scenario do?

    Isolated scenarios run with no other scenario in parallel, which is slow, so use sparingly.
  4. 4. Why does Cucumber.js with --parallel avoid many thread-safety bugs?

    Workers are separate processes, so accidental in-memory sharing is impossible, although shared external data can still clash.

Summary

  • Enable parallelism with cucumber.execution.parallel.* (JVM), --parallel (Cucumber.js) or parallel_tests (Ruby).
  • Scenarios must be independent: no shared static state, one browser each, unique data, free ports.
  • Use @ResourceLock and @Isolated for the few truly shared resources.
  • Make the suite stable sequentially first, then increase threads gradually and watch the timeline.

Next: CI pipelines with Maven and Gradle