# Split tests by time

The slowest shard sets how long CI takes. Split test files evenly by count and one shard gets the slow files while the others finish early and wait. `groundbox tests split` splits them by each file's recorded time instead, so every shard finishes at about the same moment.

## How it works

- Every job on a Groundbox runner records how long each test file took, from the test runner's own output or a JUnit report. Nothing to set up.
- `groundbox tests split --shard 2/4 <files or globs>` reads those times (each file's median over its newest 10 runs, default-branch runs first) and prints the files of shard 2 of 4, one per line.
- The slowest file goes first, each to the shard with the least time so far. A file with no history yet counts as the median. Every shard works out the same split from the same files, so each file runs exactly once.
- With no key, no history yet, or no answer from the API, it splits evenly by count and exits 0. It never fails your job.

```
$ groundbox tests split --shard 2/4 'test/**/*.test.ts'
groundbox tests split: shard 2/4, 23 of 92 files, about 183s of recorded test time (shards: 183s, 183s, 185s, 183s); ...
test/billing.test.ts
test/commands.test.ts
...
```

## In GitHub Actions

A matrix of shards, each passing its files to the test runner. Run the split in the folder the runner runs from, with the same glob it would use:

.github/workflows/ci.yml

```
jobs:
  test:
    name: test (${{ matrix.shard }}/4)
    runs-on: groundbox
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2, 3, 4]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - name: Test
        env:
          GROUNDBOX_API_KEY: ${{ secrets.GROUNDBOX_API_KEY }}
        run: |
          files=$(npx --yes @groundbox/cli tests split --shard ${{ matrix.shard }}/4 'test/**/*.test.ts')
          [ -n "$files" ] || exit 0  # more shards than files
          npx vitest run $files
```

The repository and the job come from the step: `GITHUB_REPOSITORY`, and the job that ran on `RUNNER_NAME`, all of its matrix legs together. Give `--job "test"` (the name GitHub shows, without the matrix values) to say it yourself, and `--repo owner/name` outside a job. A required check waits for each job by name, so when you shard a job that one is required for, keep a job with the old name that needs the shards.

Other runners take files the same way:

```
# jest
npx jest $(groundbox tests split --shard 2/4 'src/**/*.test.ts')

# pytest (xunit1 puts each test's file in the report)
pytest --junitxml=reports/junit.xml -o junit_family=xunit1 $(groundbox tests split --shard 2/4 'tests/**/test_*.py')

# Playwright, with its JUnit reporter on
npx playwright test $(groundbox tests split --shard 2/4 'e2e/**/*.spec.ts')
```

## Where the times come from

- **vitest and jest:** their own output in the job's log (vitest's line for each file, jest's for its slow files), or a JUnit report.
- **pytest, Playwright and the rest:** a JUnit report the job writes in its workspace, or one sent with `groundbox tests upload`. A file's time is the report's own time for it, or the sum of its tests.
- Times are kept with the job's other test results. See them with the MCP tool `get_test_timings` or the API:

```
curl "https://api.groundbox.dev/v1/ci/test-timings?repo=you/app&job=test" \
  -H "Authorization: Bearer $GROUNDBOX_API_KEY"
```

## The key

The split reads the times with an API key that has `ci:read`. Make one with only that scope on [API keys](https://app.groundbox.dev/keys) and save it as the repository secret `GROUNDBOX_API_KEY`. Pull requests from forks get no secrets, so they split by count.

## How many shards

A shard can't finish before its slowest file, and each shard repeats checkout and install. `--json` prints every shard's estimated test time (`shard_ms`): add shards while the largest drops, and stop once it is about the slowest file. A [CI tune-up](https://groundbox.dev/docs/tuneups) picks the number from your recorded times and writes the matrix for you.
