# Selectively run tests concurrently with glob patterns (/docs/guides/test/concurrent-test-glob)

<!-- agent-signals: reading_time_min: 3 · est_tokens: 1096 · updated: 2026-07-28 -->
Related: [Run your tests with the Bun test runner](/docs/guides/test/run-tests.md), [Run tests in watch mode with Bun](/docs/guides/test/watch-mode.md), [Migrate from Jest to Bun's test runner](/docs/guides/test/migrate-from-jest.md), [Mock functions in `bun test`](/docs/guides/test/mock-functions.md), [Spy on methods in `bun test`](/docs/guides/test/spy-on.md), [Set the system time in Bun's test runner](/docs/guides/test/mock-clock.md)

The `concurrentTestGlob` option in `bunfig.toml` runs tests concurrently in files whose names match a glob pattern.

## Project Structure [#project-structure]

```sh title="Project Structure" icon="folder-tree"
my-project/
├── bunfig.toml
├── tests/
│   ├── unit/
│   │   ├── math.test.ts          # Sequential
│   │   └── utils.test.ts         # Sequential
│   └── integration/
│       ├── concurrent-api.test.ts     # Concurrent
│       └── concurrent-database.test.ts # Concurrent
```

## Configuration [#configuration]

Configure your `bunfig.toml` to run test files with the "concurrent-" prefix concurrently:

```toml title="bunfig.toml" icon="settings"
[test]
# Run all test files with "concurrent-" prefix concurrently
concurrentTestGlob = "**/concurrent-*.test.ts"
```

## Test Files [#test-files]

### Unit Test (Sequential) [#unit-test-sequential]

Tests that share state or depend on ordering should stay sequential:

```ts title="tests/unit/math.test.ts" icon="/icons/typescript.svg"
import { test, expect } from "bun:test";

// These tests run sequentially by default
let sharedState = 0;

test("addition", () => {
  sharedState = 5 + 3;
  expect(sharedState).toBe(8);
});

test("uses previous state", () => {
  // This test depends on the previous test's state
  expect(sharedState).toBe(8);
});
```

### Integration Test (Concurrent) [#integration-test-concurrent]

Tests in files matching the glob pattern automatically run concurrently:

```ts title="tests/integration/concurrent-api.test.ts" icon="/icons/typescript.svg"
import { test, expect } from "bun:test";

// These tests automatically run concurrently due to filename matching the glob pattern.
// Using test() is equivalent to test.concurrent() when the file matches concurrentTestGlob.
// Each test is independent and can run in parallel.

test("fetch user data", async () => {
  const response = await fetch("/api/user/1");
  expect(response.ok).toBe(true);
});

// can also use test.concurrent() for explicitly marking it as concurrent
test.concurrent("fetch posts", async () => {
  const response = await fetch("/api/posts");
  expect(response.ok).toBe(true);
});

// can also use test.serial() for explicitly marking it as sequential
test.serial("fetch comments", async () => {
  const response = await fetch("/api/comments");
  expect(response.ok).toBe(true);
});
```

## Running Tests [#running-tests]

```bash terminal icon="terminal"
# Run all tests - concurrent-*.test.ts files will run concurrently
bun test

# Override: Force ALL tests to run concurrently
# Note: This overrides bunfig.toml and runs all tests concurrently, regardless of glob
bun test --concurrent

# Run only unit tests (sequential)
bun test tests/unit

# Run only integration tests (concurrent due to glob pattern)
bun test tests/integration
```

## Benefits [#benefits]

1. **Gradual migration**: rename files one at a time to move them to concurrent execution
2. **Clear organization**: the filename tells you how a file's tests run
3. **Performance**: independent integration tests finish faster in parallel
4. **Safety**: unit tests stay sequential where they need to

## Migration Strategy [#migration-strategy]

To migrate existing tests to concurrent execution:

1. **Start with independent integration tests** - these typically don't share state
2. **Rename files to match the glob pattern**: `mv api.test.ts concurrent-api.test.ts`
3. **Run `bun test`** - check for race conditions and flaky or unexpected failures
4. **Continue migrating stable tests** file by file

## Tips [#tips]

* **Use descriptive prefixes**: `concurrent-`, `parallel-`, `async-`
* **Keep related sequential tests together** in the same directory
* **Document why certain tests must remain sequential** with comments
* **Use `test.concurrent()` for fine-grained control** in sequential files
  (in files matched by `concurrentTestGlob`, plain `test()` already runs concurrently)

## Multiple Patterns [#multiple-patterns]

`concurrentTestGlob` also accepts multiple patterns:

```toml title="bunfig.toml" icon="settings"
[test]
concurrentTestGlob = [
  "**/integration/*.test.ts",
  "**/e2e/*.test.ts",
  "**/concurrent-*.test.ts"
]
```

Tests in files matching any of these patterns run concurrently:

* All tests in `integration/` directories
* All tests in `e2e/` directories
* All tests with `concurrent-` prefix anywhere in the project