@effect/vitest 4.0.0-beta.7 → 4.0.0-beta.71

package/src/utils.ts

@@ -1,4 +1,33 @@
 /**
+ * Assertion helpers used by `@effect/vitest` tests.
+ *
+ * This module extends Node and Vitest assertions with Effect-aware checks for
+ * values commonly returned by the library: `Option`, `Result`, and `Exit`. The
+ * helpers are synchronous assertions except `throwsAsync`, and are intended to
+ * be used after a test has already produced the value to inspect.
+ *
+ * **Mental model**
+ *
+ * `@effect/vitest` supplies the test runner integration, while this module
+ * supplies small value-level assertions. Use `it.effect` to run Effects and
+ * then call these helpers on yielded results; use ordinary Vitest tests for pure
+ * synchronous code.
+ *
+ * **Common tasks**
+ *
+ * Use `assertEquals` when equality should follow Effect's `Equal` trait, Node
+ * `strictEqual` or `deepStrictEqual` for JavaScript equality, `assertSome` and
+ * `assertNone` for `Option`, `assertSuccess` and `assertFailure` for `Result`,
+ * and `assertExitSuccess` or `assertExitFailure` when an Effect has been run to
+ * an `Exit`.
+ *
+ * **Gotchas**
+ *
+ * These helpers throw assertion errors; they do not run Effects, provide test
+ * services, or advance `TestClock`. Failed `assertEquals` checks first delegate
+ * to `deepStrictEqual` so Vitest can show a structural diff before reporting the
+ * `Equal.equals` mismatch.
+ *
  * @since 4.0.0
  */
 import type * as Cause from "effect/Cause"
@@ -17,6 +46,7 @@ import { assert as vassert } from "vitest"
 /**
  * Throws an `AssertionError` with the provided error message.
  *
+ * @category testing
  * @since 4.0.0
  */
 export function fail(message: string) {
@@ -24,8 +54,9 @@ export function fail(message: string) {
 }
 
 /**
- * Asserts that `actual` is equal to `expected` using the `Equal.equals` trait.
+ * Asserts that `actual` is deeply strictly equal to `expected` using Node's `assert.deepStrictEqual`.
  *
+ * @category testing
  * @since 4.0.0
  */
 export function deepStrictEqual<A>(actual: A, expected: A, message?: string, ..._: Array<never>) {
@@ -33,8 +64,9 @@ export function deepStrictEqual<A>(actual: A, expected: A, message?: string, ...
 }
 
 /**
- * Asserts that `actual` is not equal to `expected` using the `Equal.equals` trait.
+ * Asserts that `actual` is not deeply strictly equal to `expected` using Node's `assert.notDeepStrictEqual`.
  *
+ * @category testing
  * @since 4.0.0
  */
 export function notDeepStrictEqual<A>(actual: A, expected: A, message?: string, ..._: Array<never>) {
@@ -42,8 +74,9 @@ export function notDeepStrictEqual<A>(actual: A, expected: A, message?: string,
 }
 
 /**
- * Asserts that `actual` is equal to `expected` using the `Equal.equals` trait.
+ * Asserts that `actual` is strictly equal to `expected` using Node's `assert.strictEqual`.
  *
+ * @category testing
  * @since 4.0.0
  */
 export function strictEqual<A>(actual: A, expected: A, message?: string, ..._: Array<never>) {
@@ -53,6 +86,7 @@ export function strictEqual<A>(actual: A, expected: A, message?: string, ..._: A
 /**
  * Asserts that `actual` is equal to `expected` using the `Equal.equals` trait.
  *
+ * @category testing
  * @since 4.0.0
  */
 export function assertEquals<A>(actual: A, expected: A, message?: string, ..._: Array<never>) {
@@ -65,6 +99,7 @@ export function assertEquals<A>(actual: A, expected: A, message?: string, ..._:
 /**
  * Asserts that `thunk` does not throw an error.
  *
+ * @category testing
  * @since 4.0.0
  */
 export function doesNotThrow(thunk: () => void, message?: string, ..._: Array<never>) {
@@ -78,6 +113,7 @@ export function doesNotThrow(thunk: () => void, message?: string, ..._: Array<ne
 /**
  * Asserts that `value` is an instance of `constructor`.
  *
+ * @category testing
  * @since 4.0.0
  */
 export function assertInstanceOf<C extends abstract new(...args: any) => any>(
@@ -92,6 +128,7 @@ export function assertInstanceOf<C extends abstract new(...args: any) => any>(
 /**
  * Asserts that `self` is `true`.
  *
+ * @category testing
  * @since 4.0.0
  */
 export function assertTrue(self: unknown, message?: string, ..._: Array<never>): asserts self {
@@ -101,6 +138,7 @@ export function assertTrue(self: unknown, message?: string, ..._: Array<never>):
 /**
  * Asserts that `self` is `false`.
  *
+ * @category testing
  * @since 4.0.0
  */
 export function assertFalse(self: boolean, message?: string, ..._: Array<never>) {
@@ -110,6 +148,7 @@ export function assertFalse(self: boolean, message?: string, ..._: Array<never>)
 /**
  * Asserts that `actual` includes `expected`.
  *
+ * @category testing
  * @since 4.0.0
  */
 export function assertInclude(actual: string | undefined, expected: string, ..._: Array<never>) {
@@ -123,6 +162,7 @@ export function assertInclude(actual: string | undefined, expected: string, ..._
 /**
  * Asserts that `actual` matches `regExp`.
  *
+ * @category testing
  * @since 4.0.0
  */
 export function assertMatch(actual: string, regExp: RegExp, ..._: Array<never>) {
@@ -132,8 +172,9 @@ export function assertMatch(actual: string, regExp: RegExp, ..._: Array<never>)
 }
 
 /**
- * Asserts that `thunk` throws an error.
+ * Asserts that `thunk` throws, optionally checking the thrown value against an expected `Error` or validation function.
  *
+ * @category testing
  * @since 4.0.0
  */
 export function throws(thunk: () => void, error?: Error | ((u: unknown) => undefined), ..._: Array<never>) {
@@ -154,8 +195,9 @@ export function throws(thunk: () => void, error?: Error | ((u: unknown) => undef
 }
 
 /**
- * Asserts that `thunk` throws an error.
+ * Asserts that `thunk` throws or returns a rejected promise, optionally checking the failure value against an expected `Error` or validation function.
  *
+ * @category testing
  * @since 4.0.0
  */
 export async function throwsAsync(
@@ -184,6 +226,7 @@ export async function throwsAsync(
 /**
  * Asserts that `option` is `None`.
  *
+ * @category testing
  * @since 4.0.0
  */
 export function assertNone<A>(option: Option.Option<A>, ..._: Array<never>): asserts option is Option.None<never> {
@@ -193,6 +236,7 @@ export function assertNone<A>(option: Option.Option<A>, ..._: Array<never>): ass
 /**
  * Asserts that `a` is not `undefined`.
  *
+ * @category testing
  * @since 4.0.0
  */
 export function assertDefined<A>(
@@ -207,6 +251,7 @@ export function assertDefined<A>(
 /**
  * Asserts that `a` is `undefined`.
  *
+ * @category testing
  * @since 4.0.0
  */
 export function assertUndefined<A>(
@@ -219,8 +264,9 @@ export function assertUndefined<A>(
 }
 
 /**
- * Asserts that `option` is `Some`.
+ * Asserts that `option` is `Some` and contains a value equal to `expected`.
  *
+ * @category testing
  * @since 4.0.0
  */
 export function assertSome<A>(
@@ -236,8 +282,9 @@ export function assertSome<A>(
 // ----------------------------
 
 /**
- * Asserts that `result` is `Success`.
+ * Asserts that `result` is `Success` and contains a value equal to `expected`.
  *
+ * @category testing
  * @since 4.0.0
  */
 export function assertSuccess<A, E>(
@@ -249,8 +296,9 @@ export function assertSuccess<A, E>(
 }
 
 /**
- * Asserts that `result` is `Failure`.
+ * Asserts that `result` is `Failure` and contains an error equal to `expected`.
  *
+ * @category testing
  * @since 4.0.0
  */
 export function assertFailure<A, E>(
@@ -266,8 +314,9 @@ export function assertFailure<A, E>(
 // ----------------------------
 
 /**
- * Asserts that `exit` is a failure.
+ * Asserts that `exit` is a failure with a cause equal to `expected`.
  *
+ * @category testing
  * @since 4.0.0
  */
 export function assertExitFailure<A, E>(
@@ -279,8 +328,9 @@ export function assertExitFailure<A, E>(
 }
 
 /**
- * Asserts that `exit` is a success.
+ * Asserts that `exit` is a success with a value equal to `expected`.
  *
+ * @category testing
  * @since 4.0.0
  */
 export function assertExitSuccess<A, E>(