Skip to main content

​
Concurrency (single machine parallelism)​

When you set --concurrency N, Testpilot keeps up to N test files in flight on that machine. If you omit the flag, we apply a sensible default of 10. ::: info Mobile tests are automatically forced to 1 because simulators/devices do not support running multiple tests or instances of an application concurrently. Future releases will introduce the option to pass multiple devices to run mobile tests in parallel. ::: Typical usage: 
# Use default concurrency
testpilot test plans/

# Explicit 5-way concurrency
testpilot test --concurrency 5 plans/

# Force serial execution
testpilot test --concurrency 1 plans/

​
Sharding (splitting the suite across workers)​

Sharding tells multiple independent processes or machines to each take a deterministic slice. You specify it as current/total with a 1-based shard index: 
# First of three shards
testpilot test --shard 1/3 plans/

# Third of five shards
testpilot test --shard 3/5 plans/
Distribution is straightforward: we take the ordered test list and partition it as evenly as possible from the front. If 10 tests are split with --shard 1/3, shard 1 receives 4 tests while shards 2 and 3 receive 3 each. (The earlier shards may receive one extra when it does not divide cleanly.) There is no dynamic balancing yet; faster shards will simply finish earlier.

​
CI matrix example​

strategy:
  matrix:
    shard: [1, 2, 3, 4]
steps:
  - run: testpilot test --shard ${{ matrix.shard }}/4 plans/
Each job now owns a quarter of the list. See the documentation on GitLab Configuration for more details on how to set up sharding in your CI pipeline.

​
Caveats and nuances​

Flaky interaction: If a test appears flaky only under parallel load, re-run it with --concurrency 1. If the flake disappears, you have a shared state or isolation problem. Uneven shards: Because assignment is static and some tests naturally run longer, total build time is gated by the slowest shard. If one shard is consistently heavier, consider reorganizing test files or increasing shard count so large tests disperse. Setup overhead: Each shard performs its own initialization (dependency install, environment bootstrap, auth, etc.). Extremely high shard counts can waste time in duplicated setup; balance raw parallelism against this overhead. Resource ceilings: Concurrency does not auto-scale down; if you hit memory or CPU limits, you must lower --concurrency or reduce shard count (fewer processes overall). Mobile always remains serial, regardless of the flag. Mobile: Since mobile tests cannot be run concurrently on a single device, Testpilot forces --concurrency 1 for mobile testing to avoid simulator/device issues. Future releases will introduce the option to pass multiple devices to run mobile tests in parallel.
⌘I