@unthrown/vitest

---

@unthrown/vitest

Type Aliases

HookContext

type HookContext = object;

Defined in: index.ts:133

The slice of vitest's TestContext failOnForgottenAwait accepts, for manual wiring.

Properties

Property	Type	Defined in
task?	TaskLike	index.ts:133

---

TaskLike

type TaskLike = object;

Defined in: index.ts:131

The slice of a vitest task failOnForgottenAwait reads: a name and its parent suite.

Properties

Property	Type	Defined in
name	string	index.ts:131
suite?	TaskLike	index.ts:131

---

UnthrownMatchers

type UnthrownMatchers<R> = object;

Defined in: index.ts:462

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 awaited. A forgotten await does not pass silently: an afterEach hook (registered on import, see failOnForgottenAwait) fails the test with an explicit message naming the matchers still pending when the test ended.

Example

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

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
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
toBeErr	() => R	expect(Err("nope")).toBeErr() asserts the result is Err, regardless of the error.	index.ts:468
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
toBeErrWith	(expected) => R	-	index.ts:482
toBeOk	() => R	expect(Ok(1)).toBeOk() asserts the result is Ok, regardless of value.	index.ts:464
toBeOkWith	(value) => R	expect(Ok(1)).toBeOkWith(1) asserts the result is Ok with a deeply-equal value.	index.ts:466

Variables

toBeDefect

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

Defined in: index.ts:404

Parameters

Parameter	Type
this	MatcherState
received	unknown
expected?	unknown

Returns

ExpectationResult

---

toBeDefectWith

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

Defined in: index.ts:411

Parameters

Parameter	Type
this	MatcherState
received	unknown
expected?	unknown

Returns

ExpectationResult

---

toBeErr

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

Defined in: index.ts:345

Parameters

Parameter	Type
this	MatcherState
received	unknown
expected?	unknown

Returns

ExpectationResult

---

toBeErrWith

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

Defined in: index.ts:352

Parameters

Parameter	Type
this	MatcherState
received	unknown
expected?	unknown

Returns

ExpectationResult

---

toBeOk

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

Defined in: index.ts:331

Parameters

Parameter	Type
this	MatcherState
received	unknown
expected?	unknown

Returns

ExpectationResult

---

toBeOkWith

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

Defined in: index.ts:338

Parameters

Parameter	Type
this	MatcherState
received	unknown
expected?	unknown

Returns

ExpectationResult

Functions

failOnForgottenAwait()

function failOnForgottenAwait(context?): void;

Defined in: index.ts:233

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

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()

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

Defined in: index.ts:362

Parameters

Parameter	Type
this	MatcherState
received	unknown
tag	string
expected?	unknown

Returns

ExpectationResult