> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meow.style/llms.txt
> Use this file to discover all available pages before exploring further.

# meow:test

> The built-in test runner API — test() and a focused expect() matcher set.

`meow:test` is the API behind [`meow test`](/toolchain/test). Import it in any
`*.test.*` / `*.spec.*` file — there's nothing to install, and each file runs in
its own deterministic isolate.

```typescript theme={null}
import { test, expect } from "meow:test";

test("adds numbers", () => {
  expect(2 + 2).toBe(4);
});
```

## `test()`

```typescript theme={null}
function test(name: string, fn: () => void): void;
```

Registers a test. `meow test` runs every registered test in the file, in order, and
reports each as `✓` or `✗`.

## `expect()`

```typescript theme={null}
function expect<T>(actual: T): Expect<T>;

interface Expect<T> {
  toBe(expected: T): void;       // Object.is identity / primitive equality
  toEqual(expected: T): void;    // deep structural equality
  toBeNull(): void;
  toBeDefined(): void;
  toBeTruthy(): void;
  toBeFalsy(): void;
  toThrow(): void;               // the actual value must be a function
  readonly not: Expect<T>;       // inverts the next matcher
}
```

## Matchers

<ParamField path="toBe(expected)">
  Passes when `Object.is(actual, expected)` — identity for objects, value equality
  for primitives.
</ParamField>

<ParamField path="toEqual(expected)">
  Passes on deep structural equality — recursively compares arrays and plain
  objects.
</ParamField>

<ParamField path="toBeNull()">
  Passes when the value is exactly `null`.
</ParamField>

<ParamField path="toBeDefined()">
  Passes when the value is not `undefined`.
</ParamField>

<ParamField path="toBeTruthy() / toBeFalsy()">
  Passes on JavaScript truthiness / falsiness.
</ParamField>

<ParamField path="toThrow()">
  Calls the actual value (which must be a function) and passes if it throws.
</ParamField>

<ParamField path="not">
  Inverts the matcher that follows: `expect(x).not.toBe(y)`.
</ParamField>

## Examples

```typescript example.test.ts theme={null}
import { test, expect } from "meow:test";

test("identity vs structural equality", () => {
  expect(1 + 1).toBe(2);
  expect({ a: 1, b: [2, 3] }).toEqual({ a: 1, b: [2, 3] });
});

test("negation", () => {
  expect("meow").not.toBe("woof");
  expect([]).not.toBeNull();
});

test("truthiness and definedness", () => {
  expect("non-empty").toBeTruthy();
  expect(0).toBeFalsy();
  expect({}).toBeDefined();
});

test("throwing", () => {
  expect(() => JSON.parse("{not json}")).toThrow();
  expect(() => 42).not.toThrow();
});
```

A failing matcher throws with a readable message that the runner surfaces under the
test name:

```text theme={null}
  ✗ adds numbers
    expect(5).toBe(4)
```

<Note>
  Because every test file runs in a deterministic isolate (frozen clock, seeded
  RNG, pinned timezone), assertions on time- or random-derived values are stable.
  See [Testing](/toolchain/test) and [Determinism](/concepts/determinism).
</Note>

<Card title="Run your tests" icon="play" href="/toolchain/test">
  The meow test command, discovery rules, and output.
</Card>