---
url: /unthrown/api/vitest.md
---
**@unthrown/vitest**

***

# @unthrown/vitest

## Type Aliases

### HookContext

```ts
type HookContext = object;
```

Defined in: [index.ts:133](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/vitest/src/index.ts#L133)

The slice of vitest's `TestContext` [failOnForgottenAwait](#failonforgottenawait) accepts, for manual wiring.

#### Properties

| Property | Type | Defined in |
| ------ | ------ | ------ |
|  `task?` | [`TaskLike`](#tasklike) | [index.ts:133](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/vitest/src/index.ts#L133) |

***

### TaskLike

```ts
type TaskLike = object;
```

Defined in: [index.ts:131](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/vitest/src/index.ts#L131)

The slice of a vitest task [failOnForgottenAwait](#failonforgottenawait) reads: a name and its parent suite.

#### Properties

| Property | Type | Defined in |
| ------ | ------ | ------ |
|  `name` | `string` | [index.ts:131](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/vitest/src/index.ts#L131) |
|  `suite?` | [`TaskLike`](#tasklike) | [index.ts:131](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/vitest/src/index.ts#L131) |

***

### UnthrownMatchers

```ts
type UnthrownMatchers<R> = object;
```

Defined in: [index.ts:462](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/vitest/src/index.ts#L462)

The matchers `@unthrown/vitest` contributes to Vitest's `expect`. For an
`AsyncResult`, `await` the assertion; `toBeOkWith` compares deeply.

#### Remarks

Import the package once (e.g. in a test setup file) to register the
matchers and pull in this type augmentation.

For an `AsyncResult` the assertion is asynchronous and must be `await`ed.
A forgotten `await` does not pass silently: an `afterEach` hook (registered
on import, see [failOnForgottenAwait](#failonforgottenawait)) fails the test with an explicit
message naming the matchers still pending when the test ended.

#### Example

```ts
import "@unthrown/vitest";
import { Ok, fromSafePromise } from "unthrown";
import { expect, test } from "vitest";

test("sync", () => {
  expect(Ok(1)).toBeOkWith(1);
});

test("async", async () => {
  await expect(fromSafePromise(Promise.resolve(1))).toBeOk();
});
```

#### See

[The Testing guide](https://btravstack.github.io/unthrown/how-to/test-with-vitest)

#### Type Parameters

| Type Parameter | Default type | Description |
| ------ | ------ | ------ |
| `R` | `unknown` | the assertion's chaining return type. |

#### Properties

| Property | Type | Description | Defined in |
| ------ | ------ | ------ | ------ |
|  `toBeDefect` | () => `R` | `expect(result).toBeDefect()` asserts the result is a `Defect`. | [index.ts:484](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/vitest/src/index.ts#L484) |
|  `toBeDefectWith` | (`expected`) => `R` | Assert a `Defect` whose `cause` is deeply equal to `expected`. `expected` is typed `unknown` because **a defect's cause is `unknown` by design**: nothing reaches that channel through a typed error, so there is no tighter type to give it and no tag-aware variant to add. An asymmetric matcher works as elsewhere: `expect(result).toBeDefectWith(expect.any(TypeError))`. | [index.ts:494](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/vitest/src/index.ts#L494) |
|  `toBeErr` | () => `R` | `expect(Err("nope")).toBeErr()` asserts the result is `Err`, regardless of the error. | [index.ts:468](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/vitest/src/index.ts#L468) |
|  `toBeErrTagged` | (`tag`, `expected?`) => `R` | Assert an `Err` whose error has `_tag === tag`. Optionally pass `expected` to also match the error's payload — its own props minus the keys `TaggedError` reserves (`_tag`, `name`, `message`, `stack`), so a subclass's `override message = "…"` does not leak into an exact assertion. A plain object matches exactly, an asymmetric matcher (e.g. `expect.objectContaining(...)`) matches partially. An explicitly-passed `undefined` asserts the payload equals `undefined` (it does not degrade to tag-only). `expect(result).toBeErrTagged("NotFound", { id })` asserts the tag and payload. | [index.ts:481](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/vitest/src/index.ts#L481) |
|  `toBeErrWith` | (`expected`) => `R` | - | [index.ts:482](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/vitest/src/index.ts#L482) |
|  `toBeOk` | () => `R` | `expect(Ok(1)).toBeOk()` asserts the result is `Ok`, regardless of value. | [index.ts:464](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/vitest/src/index.ts#L464) |
|  `toBeOkWith` | (`value`) => `R` | `expect(Ok(1)).toBeOkWith(1)` asserts the result is `Ok` with a deeply-equal value. | [index.ts:466](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/vitest/src/index.ts#L466) |

## Variables

### toBeDefect

```ts
const toBeDefect: (this, received, expected?) => ExpectationResult;
```

Defined in: [index.ts:404](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/vitest/src/index.ts#L404)

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `this` | `MatcherState` |
| `received` | `unknown` |
| `expected?` | `unknown` |

#### Returns

`ExpectationResult`

***

### toBeDefectWith

```ts
const toBeDefectWith: (this, received, expected?) => ExpectationResult;
```

Defined in: [index.ts:411](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/vitest/src/index.ts#L411)

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `this` | `MatcherState` |
| `received` | `unknown` |
| `expected?` | `unknown` |

#### Returns

`ExpectationResult`

***

### toBeErr

```ts
const toBeErr: (this, received, expected?) => ExpectationResult;
```

Defined in: [index.ts:345](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/vitest/src/index.ts#L345)

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `this` | `MatcherState` |
| `received` | `unknown` |
| `expected?` | `unknown` |

#### Returns

`ExpectationResult`

***

### toBeErrWith

```ts
const toBeErrWith: (this, received, expected?) => ExpectationResult;
```

Defined in: [index.ts:352](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/vitest/src/index.ts#L352)

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `this` | `MatcherState` |
| `received` | `unknown` |
| `expected?` | `unknown` |

#### Returns

`ExpectationResult`

***

### toBeOk

```ts
const toBeOk: (this, received, expected?) => ExpectationResult;
```

Defined in: [index.ts:331](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/vitest/src/index.ts#L331)

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `this` | `MatcherState` |
| `received` | `unknown` |
| `expected?` | `unknown` |

#### Returns

`ExpectationResult`

***

### toBeOkWith

```ts
const toBeOkWith: (this, received, expected?) => ExpectationResult;
```

Defined in: [index.ts:338](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/vitest/src/index.ts#L338)

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `this` | `MatcherState` |
| `received` | `unknown` |
| `expected?` | `unknown` |

#### Returns

`ExpectationResult`

## Functions

### failOnForgottenAwait()

```ts
function failOnForgottenAwait(context?): void;
```

Defined in: [index.ts:233](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/vitest/src/index.ts#L233)

The check behind the registered `afterEach` hook: when async matcher
assertions are still pending at the end of a test — a forgotten `await` —
it abandons them (so they cannot late-fire as unhandled rejections) and
throws an error naming the un-awaited matchers, failing that test.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `context?` | [`HookContext`](#hookcontext) |

#### Returns

`void`

#### Remarks

You never need to call this yourself: importing the package registers it as
an `afterEach` hook alongside the matchers. It is exported so the mechanism
itself is testable.

***

### toBeErrTagged()

```ts
function toBeErrTagged(
   this, 
   received, 
   tag, 
   expected?
): ExpectationResult;
```

Defined in: [index.ts:362](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/vitest/src/index.ts#L362)

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `this` | `MatcherState` |
| `received` | `unknown` |
| `tag` | `string` |
| `expected?` | `unknown` |

#### Returns

`ExpectationResult`