> ## Documentation Index
> Fetch the complete documentation index at: https://bun-1dd33a4e-farm-ad2450b3-transpiler-cache-version-namespa.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Finding tests

> Learn how Bun's test runner discovers and filters test files in your project

`bun test` decides which files to run as tests by matching their paths against a set of patterns.

## Default Discovery Logic

By default, `bun test` recursively searches the project directory for files that match these patterns:

* `*.test.{js|jsx|ts|tsx}` - Files ending with `.test.js`, `.test.jsx`, `.test.ts`, or `.test.tsx`
* `*_test.{js|jsx|ts|tsx}` - Files ending with `_test.js`, `_test.jsx`, `_test.ts`, or `_test.tsx`
* `*.spec.{js|jsx|ts|tsx}` - Files ending with `.spec.js`, `.spec.jsx`, `.spec.ts`, or `.spec.tsx`
* `*_spec.{js|jsx|ts|tsx}` - Files ending with `_spec.js`, `_spec.jsx`, `_spec.ts`, or `_spec.tsx`

## Exclusions

By default, `bun test` ignores:

* `node_modules` directories
* Hidden directories (those starting with a period `.`)
* Files that don't have JavaScript-like extensions (based on available [loaders](/bundler/loaders))

## Customizing Test Discovery

### Position Arguments as Filters

To filter which test files run, pass additional positional arguments to `bun test`:

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun test <filter> <filter> ...
```

Any test file with a path that contains one of the filters runs. Filters are substring matches, not glob patterns.

For example, to run all tests in a `utils` directory:

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun test utils
```

This matches files like `src/utils/string.test.ts` and `lib/utils/array_test.js`.

### Specifying Exact File Paths

To run a specific file in the test runner, make sure the path starts with `./` or `/` to distinguish it from a filter name:

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun test ./test/specific-file.test.ts
```

### Filter by Test Name

To filter tests by name rather than file path, use the `-t`/`--test-name-pattern` flag with a regex pattern:

```sh terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# run all tests with "addition" in the name
bun test --test-name-pattern addition
```

The pattern is matched against the test name prefixed with the labels of all its parent `describe` blocks, separated by spaces. For example, a test defined as:

```ts title="math.test.ts" icon="https://mintcdn.com/bun-1dd33a4e-farm-ad2450b3-transpiler-cache-version-namespa/pVrMBuZvntvIe2NO/icons/typescript.svg?fit=max&auto=format&n=pVrMBuZvntvIe2NO&q=85&s=81fcaf3ac2cead5d758f3588a492f46a" theme={"theme":{"light":"github-light","dark":"dracula"}}
describe("Math", () => {
  describe("operations", () => {
    test("should add correctly", () => {
      // ...
    });
  });
});
```

This test is matched against the string "Math operations should add correctly".

### Changing the Root Directory

By default, Bun looks for test files starting from the current working directory. Change this with the `root` option in `bunfig.toml`:

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[test]
root = "src"  # Only scan for tests in the src directory
```

## Execution Order

Tests run in the following order:

1. Test files run sequentially (not in parallel)
2. Within each file, tests run sequentially in definition order