Bun Test Basics

secondsky/claude-skills/plugins/bun/skills/bun-test-basics

by secondsky88378361314fMIT227 starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated 10 days ago

Use for bun:test syntax, assertions, describe/it, test.skip/only/each, and basic patterns.

Instructions onlySoftware Development

AI-generated overview

Reference guide for Bun's built-in test runner: syntax, assertions, modifiers, and CLI options.

What it does: This skill provides reference documentation for writing and running tests with Bun's built-in Jest-compatible test runner. It covers test file naming patterns, describe/it structure, test modifiers such as skip, only, todo, and failing, parameterized and concurrent tests, a broad list of common matchers, CLI options, output reporters, and common error fixes. It produces guidance and code examples rather than executable artifacts.
When to use it: Use it when writing or reviewing tests that run under Bun and you need the correct syntax, matcher, or CLI flag. It is also useful for troubleshooting common bun test errors such as timeouts or missing imports.
Requirements: Requires the Bun runtime to run the tests being described. No scripts or assets ship with the skill; it is instructions and examples only.

Bun Test Basics

Bun ships with a fast, built-in, Jest-compatible test runner. Tests run with the Bun runtime and support TypeScript/JSX natively.

Quick Start

bash

# Run all testsbun test
# Run specific filebun test ./test/math.test.ts
# Run tests matching patternbun test --test-name-pattern "addition"

# Run all testsbun test
# Run specific filebun test ./test/math.test.ts
# Run tests matching patternbun test --test-name-pattern "addition"

Writing Tests

typescript

import { test, expect, describe } from "bun:test";
test("2 + 2", () => {  expect(2 + 2).toBe(4);});
describe("math", () => {  test("addition", () => {    expect(1 + 1).toBe(2);  });
  test("subtraction", () => {    expect(5 - 3).toBe(2);  });});

import { test, expect, describe } from "bun:test";
test("2 + 2", () => {  expect(2 + 2).toBe(4);});
describe("math", () => {  test("addition", () => {    expect(1 + 1).toBe(2);  });
  test("subtraction", () => {    expect(5 - 3).toBe(2);  });});

Test File Patterns

Bun discovers test files matching:

*.test.{js|jsx|ts|tsx}
*_test.{js|jsx|ts|tsx}
*.spec.{js|jsx|ts|tsx}
*_spec.{js|jsx|ts|tsx}

Test Modifiers

typescript

// Skip a testtest.skip("not ready", () => {  // won't run});
// Only run this testtest.only("focus on this", () => {  // other tests won't run});// NOTE: in Bun 1.3+ `bun test` exits non-zero in CI when a file uses// `test.only`. Use it for local debugging only — never commit it.
// Placeholder for future testtest.todo("implement later");
// Expected to failtest.failing("known bug", () => {  throw new Error("This is expected");});

// Skip a testtest.skip("not ready", () => {  // won't run});
// Only run this testtest.only("focus on this", () => {  // other tests won't run});// NOTE: in Bun 1.3+ `bun test` exits non-zero in CI when a file uses// `test.only`. Use it for local debugging only — never commit it.
// Placeholder for future testtest.todo("implement later");
// Expected to failtest.failing("known bug", () => {  throw new Error("This is expected");});

Parameterized Tests

typescript

test.each([  [1, 1, 2],  [2, 2, 4],  [3, 3, 6],])("add(%i, %i) = %i", (a, b, expected) => {  expect(a + b).toBe(expected);});
// With objectstest.each([  { a: 1, b: 2, expected: 3 },  { a: 5, b: 5, expected: 10 },])("add($a, $b) = $expected", ({ a, b, expected }) => {  expect(a + b).toBe(expected);});

test.each([  [1, 1, 2],  [2, 2, 4],  [3, 3, 6],])("add(%i, %i) = %i", (a, b, expected) => {  expect(a + b).toBe(expected);});
// With objectstest.each([  { a: 1, b: 2, expected: 3 },  { a: 5, b: 5, expected: 10 },])("add($a, $b) = $expected", ({ a, b, expected }) => {  expect(a + b).toBe(expected);});

Concurrent Tests

typescript

// Run tests in paralleltest.concurrent("async test 1", async () => {  await fetch("/api/1");});
test.concurrent("async test 2", async () => {  await fetch("/api/2");});
// Force sequential when using --concurrenttest.serial("must run alone", () => {  // runs sequentially});

// Run tests in paralleltest.concurrent("async test 1", async () => {  await fetch("/api/1");});
test.concurrent("async test 2", async () => {  await fetch("/api/2");});
// Force sequential when using --concurrenttest.serial("must run alone", () => {  // runs sequentially});

Common Matchers

typescript

// Equalityexpect(value).toBe(4);           // Strict equalityexpect(obj).toEqual({ a: 1 });   // Deep equalityexpect(value).toStrictEqual(4);  // Strict + type
// Truthinessexpect(value).toBeTruthy();expect(value).toBeFalsy();expect(value).toBeNull();expect(value).toBeDefined();expect(value).toBeUndefined();
// Numbersexpect(value).toBeGreaterThan(3);expect(value).toBeGreaterThanOrEqual(3);expect(value).toBeLessThan(5);expect(value).toBeCloseTo(0.3, 5);  // Floating point
// Stringsexpect(str).toMatch(/pattern/);expect(str).toContain("substring");expect(str).toStartWith("Hello");expect(str).toEndWith("world");
// Arraysexpect(arr).toContain(item);expect(arr).toContainEqual({ a: 1 });expect(arr).toHaveLength(3);
// Objectsexpect(obj).toHaveProperty("key");expect(obj).toHaveProperty("key", value);expect(obj).toMatchObject({ a: 1 });
// Exceptionsexpect(() => fn()).toThrow();expect(() => fn()).toThrow("message");expect(() => fn()).toThrow(CustomError);
// Asyncawait expect(promise).resolves.toBe(value);await expect(promise).rejects.toThrow();
// Negationexpect(value).not.toBe(5);

// Equalityexpect(value).toBe(4);           // Strict equalityexpect(obj).toEqual({ a: 1 });   // Deep equalityexpect(value).toStrictEqual(4);  // Strict + type
// Truthinessexpect(value).toBeTruthy();expect(value).toBeFalsy();expect(value).toBeNull();expect(value).toBeDefined();expect(value).toBeUndefined();
// Numbersexpect(value).toBeGreaterThan(3);expect(value).toBeGreaterThanOrEqual(3);expect(value).toBeLessThan(5);expect(value).toBeCloseTo(0.3, 5);  // Floating point
// Stringsexpect(str).toMatch(/pattern/);expect(str).toContain("substring");expect(str).toStartWith("Hello");expect(str).toEndWith("world");
// Arraysexpect(arr).toContain(item);expect(arr).toContainEqual({ a: 1 });expect(arr).toHaveLength(3);
// Objectsexpect(obj).toHaveProperty("key");expect(obj).toHaveProperty("key", value);expect(obj).toMatchObject({ a: 1 });
// Exceptionsexpect(() => fn()).toThrow();expect(() => fn()).toThrow("message");expect(() => fn()).toThrow(CustomError);
// Asyncawait expect(promise).resolves.toBe(value);await expect(promise).rejects.toThrow();
// Negationexpect(value).not.toBe(5);

CLI Options

bash

# Timeout per test (default 5000ms)bun test --timeout 20
# Bail after N failuresbun test --bailbun test --bail=10
# Watch modebun test --watch
# Random orderbun test --randomizebun test --seed 12345
# Concurrent executionbun test --concurrentbun test --concurrent --max-concurrency 4
# Filter by namebun test -t "pattern"

# Timeout per test (default 5000ms)bun test --timeout 20
# Bail after N failuresbun test --bailbun test --bail=10
# Watch modebun test --watch
# Random orderbun test --randomizebun test --seed 12345
# Concurrent executionbun test --concurrentbun test --concurrent --max-concurrency 4
# Filter by namebun test -t "pattern"

Output Reporters

bash

# Dots (compact)bun test --dots
# JUnit XML (CI/CD)bun test --reporter=junit --reporter-outfile=./results.xml

# Dots (compact)bun test --dots
# JUnit XML (CI/CD)bun test --reporter=junit --reporter-outfile=./results.xml

Common Errors

Error	Cause	Fix
`Test timeout`	Test exceeds 5s	Use `--timeout` or optimize
`No tests found`	Wrong file pattern	Check file naming
`expect is not defined`	Missing import	Import from `bun:test`
`Assertion failed`	Test failure	Check expected vs actual

When to Load References

Load references/matchers.md when:

Need complete matcher reference
Custom matcher patterns

Load references/cli-options.md when:

Full CLI flag reference
Advanced execution options

Source and attribution

Source:secondsky/claude-skillsinplugins/bun/skills/bun-test-basicsat commit8837836

License: MIT

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

Bun Test Basics

Bun Test Basics

Quick Start

Writing Tests

Test File Patterns

Test Modifiers

Parameterized Tests

Concurrent Tests

Common Matchers

CLI Options

Output Reporters

Common Errors

When to Load References

Source and attribution

More from secondsky/claude-skills

Vulnerability Scanning

Web Performance Optimization

Web Performance Audit

Threejs

Tailwind V4 Shadcn

Technical Specification

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices