Skip to content
GroundboxDocs
API referenceStatusPricing
DashboardStart free
GroundboxGitHub Actions runners and Linux sandboxes for AI agents. One key, one bill.System status

Product

CI runnersSandboxesBuilds and cacheAgent computersPricing

Developers

DocsAPI referenceAPI explorerCLIMCP serverBenchmark

Compare

vs GitHub-hostedvs Blacksmithvs E2Bvs DaytonaAll comparisons

Company

Talk to usSupportcontact@groundbox.devGroundmail ↗
© 2026 Groundbox
TermsPrivacyllms.txt
OverviewCI in one lineFirst sandboxHand it to your agent
Sizes and labelsCachesBuild cachesMigrateci waitTerminal on a jobPublic repositoriesAuto sizeAuto size: own runnersFlexCI tune-upSplit tests by timeDocker buildsGitLab CI
Start, exec, filesFrom a Docker imageCommandsForkTime machineSnapshotsPause and resumeStop and startIdle pause and wakeScheduled runsPreviewsSecretsEgress allowlistFlex sandboxesTemplatesVolumes
Push and pullIn GitHub ActionsStorage and retention
Desktop and actionsLive view in your appHuman handoffSign in onceAgent loop example
BucketsAccess keysMount a bucket
Move from Runloop
Omnara
REST APIAPI explorerOpenAPI referenceCLIMCP serverSDKsKeys and capsLeave or delete a team
  1. CI runners
  2. Split tests by time
Markdown
Open in
ClaudeChatGPT
On this page

    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.
    Text
    $ 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:

    Terminal
    # 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:
    Terminal
    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 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 picks the number from your recorded times and writes the matrix for you.

    ← PreviousCI tune-upNext →Docker builds
    System statusSupportPricingllms.txtgroundbox.dev