How to Balance Test Shards With Knapsack Pro

Knapsack Pro Queue Mode assigns tests to nodes at runtime, so a slow node simply receives fewer remaining tests.

Instead of splitting upfront, Queue Mode has each node request the next test from the Knapsack API, self-balancing as the run proceeds.

Steps

• Add the Knapsack Pro adapter for your test runner.
• Set KNAPSACK_PRO_CI_NODE_TOTAL and KNAPSACK_PRO_CI_NODE_INDEX per job.
• Provide KNAPSACK_PRO_TEST_SUITE_TOKEN as a secret.

Workflow

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        ci_node_index: [0, 1, 2]
    env:
      KNAPSACK_PRO_CI_NODE_TOTAL: 3
      KNAPSACK_PRO_CI_NODE_INDEX: ${{ matrix.ci_node_index }}
      KNAPSACK_PRO_TEST_SUITE_TOKEN: ${{ secrets.KNAPSACK_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx knapsack-pro-jest

Gotchas

• Queue Mode needs network access to the Knapsack API during the run.
• Node total must match the matrix length or some tests never get assigned.

Related guides