Skip to main content
Speed up your test suite by running multiple tests simultaneously. TestDriver’s parallel execution capabilities let you maximize throughput and reduce overall test duration.

​
Quick Start

Enable parallel execution in your Vitest configuration:
vitest.config.mjs
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    testTimeout: 120000,
    maxConcurrency: 10, // Run 10 tests simultaneously
  },
});

​
Performance Comparison

See the dramatic difference parallel execution makes:

Sequential Execution

Parallel Execution (3x)

3x faster - Run tests in parallel to dramatically reduce total execution time.

​
Real-World Example

Here’s how parallel execution impacts a real test suite: 
$ npx vitest run --maxConcurrency=1

 ✓ test/login.test.js (3 tests) 87.4s
 ✓ test/checkout.test.js (5 tests) 142.6s
 ✓ test/profile.test.js (4 tests) 98.2s

 Test Files: 3 passed (3)
 Tests: 12 passed (12)
 Duration: 328.2s

​
Configuration Options

Fine-tune parallel execution for your needs:
vitest.config.mjs
export default defineConfig({
  test: {
    maxConcurrency: 10, // Max parallel tests
  },
});
Control how many tests run simultaneously.

​
Best Practices

// Development: Lower concurrency for easier debugging
maxConcurrency: 3

// CI: Higher concurrency for speed
maxConcurrency: 20
Balance speed with resource usage. Too many concurrent tests can overwhelm your system or CI runner.Guidelines:
  • Local development: 3-5 concurrent tests
  • CI with 2 CPUs: 5-10 concurrent tests
  • CI with 4+ CPUs: 10-20 concurrent tests
// ✅ Good - each test is isolated
test('login test 1', async (context) => {
  const { testdriver } = await chrome(context, {
    url: 'https://example.com'
  });
  // Test runs in its own sandbox
});

test('login test 2', async (context) => {
  const { testdriver } = await chrome(context, {
    url: 'https://example.com'
  });
  // Different sandbox, no interference
});
TestDriver automatically provisions isolated sandboxes for each test, preventing interference.
# Watch CPU and memory during test runs
# macOS
top -l 1 | grep -E "(CPU|PhysMem)"

# Linux
top -bn1 | grep "Cpu(s)"

# Adjust maxConcurrency if system is overwhelmed
Keep an eye on system resources to find the optimal concurrency level.
.github/workflows/test.yml
strategy:
  matrix:
    shard: [1, 2, 3, 4]
steps:
  - run: npx vitest run --shard=${{ matrix.shard }}/4
Split tests across multiple CI jobs for massive test suites.

​
Combining with Caching

Parallel execution + intelligent caching = maximum speed: 
// With both parallelization and caching enabled:
✅ Cache-accelerated parallel execution:
   Total: 15s (6x faster than sequential, no cache)
When you combine:
  • Parallel execution: Run multiple tests at once
  • Intelligent caching: Skip redundant AI analysis
You get exponential performance improvements. Learn about Intelligent Caching

​
Troubleshooting

Cause: Tests may have hidden dependencies or shared state.Solution:
// Check for shared resources
test.sequential('sequential test group', () => {
  test('test 1', async () => { /* ... */ });
  test('test 2', async () => { /* ... */ });
});
Or run with lower concurrency to identify the issue:
npx vitest run --maxConcurrency=1
Cause: Too many concurrent tests for available resources.Solution:
vitest.config.mjs
export default defineConfig({
  test: {
    maxConcurrency: process.env.CI ? 10 : 5, // Reduce CI concurrency
  },
});
Cause: System overhead from too many workers.Solution:
// Try different concurrency levels
maxConcurrency: 3  // Start low
maxConcurrency: 5
maxConcurrency: 10 // Increase until performance degrades
Find the sweet spot for your system.

​
CI/CD Configuration

.github/workflows/test.yml
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        shard: [1, 2, 3, 4]
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm install
      
      - name: Run tests (shard ${{ matrix.shard }}/4)
        run: npx vitest run --shard=${{ matrix.shard }}/4
        env:
          TD_API_KEY: ${{ secrets.TD_API_KEY }}

​
Next Steps

Intelligent Caching

Speed up tests with smart caching

Running Tests

Learn how to run your test suite

Setting Up in CI

Configure CI/CD pipelines

Performance Guide

Optimize test performance