@unthrown/vitest

---

@unthrown/vitest

Type Aliases

UnthrownMatchers

type UnthrownMatchers<R> = object;

Defined in: index.ts:377

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

Functions

failOnForgottenAwait()

function failOnForgottenAwait(context?): void;

Defined in: index.ts:183

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.

---

toBeDefect()

function toBeDefect(this, received): ExpectationResult;

Defined in: index.ts:327

Parameters

Parameter	Type
this	MatcherState
received	unknown

Returns

ExpectationResult

---

toBeErr()

function toBeErr(this, received): ExpectationResult;

Defined in: index.ts:256

Parameters

Parameter	Type
this	MatcherState
received	unknown

Returns

ExpectationResult

---

toBeErrTagged()

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

Defined in: index.ts:285

Parameters

Parameter	Type
this	MatcherState
received	unknown
tag	string
expected?	unknown

Returns

ExpectationResult

---

toBeErrWith()

function toBeErrWith(
   this, 
   received, 
   expected): ExpectationResult;

Defined in: index.ts:270

Parameters

Parameter	Type
this	MatcherState
received	unknown
expected	unknown

Returns

ExpectationResult

---

toBeOk()

function toBeOk(this, received): ExpectationResult;

Defined in: index.ts:227

Parameters

Parameter	Type
this	MatcherState
received	unknown

Returns

ExpectationResult

---

toBeOkWith()

function toBeOkWith(
   this, 
   received, 
   expected): ExpectationResult;

Defined in: index.ts:241

Parameters

Parameter	Type
this	MatcherState
received	unknown
expected	unknown

Returns

ExpectationResult