@effect/vitest 4.0.0-beta.9 → 4.0.0-beta.90

package/src/utils.ts

@@ -1,4 +1,12 @@
 /**
+ * Provides assertion helpers used by `@effect/vitest` tests.
+ *
+ * This module defines small assertion functions built on Node's `assert`,
+ * Vitest's instance checks, and Effect's equality support. The helpers cover
+ * basic equality, thrown errors, defined and undefined values, strings, regular
+ * expressions, class instances, `Option`, `Result`, and `Exit`. Most helpers are
+ * synchronous; `throwsAsync` handles rejected promises.
+ *
  * @since 4.0.0
  */
 import type * as Cause from "effect/Cause"
@@ -15,8 +23,9 @@ import { assert as vassert } from "vitest"
 // ----------------------------
 
 /**
- * Throws an `AssertionError` with the provided error message.
+ * Fails the current test with the provided error message.
  *
+ * @category testing
  * @since 4.0.0
  */
 export function fail(message: string) {
@@ -24,8 +33,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 +43,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 +53,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 +65,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 +78,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 +92,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 +107,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 +117,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 +127,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 +141,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 +151,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 +174,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 +205,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 +215,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 +230,7 @@ export function assertDefined<A>(
 /**
  * Asserts that `a` is `undefined`.
  *
+ * @category testing
  * @since 4.0.0
  */
 export function assertUndefined<A>(
@@ -219,8 +243,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 +261,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 +275,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 +293,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 +307,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>(