Parallel Cypress runs in Bitbucket Pipelines without Cypress Cloud
Cypress's --parallel flag only works with --record, because Cypress Cloud is what hands specs out to the machines. Without a record key you can still run in parallel on Bitbucket Pipelines: list the specs, sort them, and give each parallel step every Nth one using BITBUCKET_PARALLEL_STEP and BITBUCKET_PARALLEL_STEP_COUNT. Guard the case where a step gets no specs, because an empty --spec means "run everything".
Why the pipeline needed to run without Cypress Cloud
I was adding end-to-end tests to the pipeline of a decoupled Drupal site with a Next.js front end. The test pipeline was modelled on one that already existed for a sibling project, and that one used Cypress Cloud: six parallel steps, each running cypress run --record --parallel with a shared --ci-build-id, and Cloud balancing the specs between them.
The new project had no Cloud record key configured. A secret that has to exist before CI works is also a secret that forks, new repositories and some pull request builds won't have, so the step needed two modes: use Cloud when a key is present, and split the work itself when it isn't.
How to split specs across Bitbucket parallel steps
Bitbucket Pipelines tells each step in a parallel group which one it is. BITBUCKET_PARALLEL_STEP is its zero-based index and BITBUCKET_PARALLEL_STEP_COUNT is the size of the group. That is enough for a round-robin split: sort the spec files so every step sees the same list, then keep the ones whose position modulo the count equals this step's index.
#!/usr/bin/env bash
# Pick this parallel step's share of the specs.
set -uo pipefail
index="${BITBUCKET_PARALLEL_STEP:-0}"
count="${BITBUCKET_PARALLEL_STEP_COUNT:-1}"
specs=$(find cypress/e2e -name '*.cy.js' | sort \
| awk -v i="$index" -v n="$count" '(NR - 1) % n == i' \
| paste -sd, -)
echo "Step $((index + 1))/$count runs: ${specs:-nothing}"
if [ -z "$specs" ]; then
exit 0
fi
npx cypress run --browser chrome --spec "$specs"
The defaults matter: run outside a parallel group, the script falls back to step 0 of 1 and runs everything, so the same script works locally.
The empty check matters more. With six steps and a small, tag-filtered suite, some steps can end up with nothing to do. Pass an empty string to --spec and Cypress doesn't run zero specs; it runs its default spec pattern, which is the whole suite. You would get six full runs and believe you had six shares.
In the pipeline file, a YAML anchor keeps the parallel steps identical. Each copy only changes its name:
definitions:
steps:
- step: &e2e
name: End-to-end
script:
- ./ci/run-cypress.sh
pipelines:
pull-requests:
'**':
- parallel:
- step: { <<: *e2e, name: E2E 1/3 }
- step: { <<: *e2e, name: E2E 2/3 }
- step: { <<: *e2e, name: E2E 3/3 }
When a record key is set, the same step takes the other path and runs --record --parallel --ci-build-id "$BITBUCKET_BUILD_NUMBER" instead, so the project can move to Cloud later without touching the pipeline.
Combining the split with test tags
The suite is tagged with @cypress/grep: a small @smoke set runs on every pull request, and a larger @regression set runs from a custom pipeline you trigger by hand, with the tag passed in as a pipeline variable. Filtering by tag inside Cypress isn't enough on its own, because a step that gets a share of specs with no matching tests still boots Cypress for each of them. Filter the file list first, then split it, so every step gets a share of specs that will actually run. @cypress/grep's grepFilterSpecs option does the same pre-filtering inside Cypress if you prefer not to do it in shell.
What each parallel step has to build
The awkward part of end-to-end tests for a decoupled site is that every parallel step needs the whole stack: a database restored from a recent backup, Drupal with its config imported, a fresh test user, the Next.js front end built and started, and Redis for the front end's cache handler. Bitbucket services and caches help (MySQL and Redis as services; Composer, Yarn, the Next.js build cache and the Cypress binary cached between runs), but the setup still runs once per step. More steps means more total build minutes even when the wall-clock time falls, which is the main reason not to set the count higher than the suite needs.
A few things broke along the way that are worth knowing about:
- Don't serve Drupal with
drush runserver. It uses PHP's built-in web server, which handles one request at a time by default. A Next.js build and a browser test both make concurrent requests to Drupal, so pages stall. Starting Apache in the step image fixed it. - Use a hostname, not a bare IP. The front end's middleware treated any host it didn't recognise as production and tried to redirect it. Adding an
/etc/hostsentry that matched the existing local-development bypass was simpler and safer than adding a CI special case to the middleware. - Generate throwaway secrets when none are set. The preview and revalidation secrets only have to match between this step's own Drupal and its own front end, so the step uses
${SECRET:-$(cat /proc/sys/kernel/random/uuid)}. Repositories without those variables still get a working pipeline. - Print the logs without losing the exit code. Run Cypress with
set +e, save$?, print the tail of the front end's log, thenexitwith the saved code. - Put Drupal's errors in
after-script.after-scriptruns even when the main script fails, including failures before Cypress starts, and it can't change the step's result. Dumping the latest error-level watchdog entries there means a 500 from Drupal shows its real cause in the pipeline log.
What you give up without Cypress Cloud
Round-robin by filename balances the number of specs, not their duration. Cloud uses timings from previous runs to give each machine a similar amount of work; a modulo split can put three slow specs on one step and three quick ones on another, and the pipeline waits for the slowest. You also lose Cloud's dashboard, flake detection and recordings, though Cypress's own screenshots and videos can be kept as pipeline artifacts.
For a smoke suite on pull requests I think that's a fair trade: no extra secret, no extra service, and the same pipeline runs everywhere. If one step regularly finishes long after the others, that is the signal to split the slow specs, sort by a recorded duration instead of by name, or add a record key and let the pipeline switch to Cloud.
Key takeaways
- Cypress
--parallelrequires--recordand Cypress Cloud; without them, split the specs yourself. - Bitbucket's
BITBUCKET_PARALLEL_STEPandBITBUCKET_PARALLEL_STEP_COUNTgive each step enough information for a deterministic modulo split of a sorted spec list. - Always skip the Cypress run when a step's share of specs is empty, because an empty
--specruns the whole suite. - Filter specs by tag before splitting them, so every parallel step gets work that will actually run.
- A round-robin split balances spec counts rather than durations, so watch for one step that consistently finishes last.