@effect/vitest 4.0.0-beta.66 → 4.0.0-beta.68

package/src/utils.ts

@@ -1,4 +1,18 @@
 /**
+ * Assertion utilities for `@effect/vitest` test suites.
+ *
+ * This module collects small assertion helpers for common Effect testing
+ * scenarios: Node-style equality checks, `Equal.equals` comparisons, string
+ * matching, thrown error validation, and focused assertions for `Option`,
+ * `Result`, and `Exit` values. They are intended to be imported as `assert`
+ * helpers from `@effect/vitest` and used in both regular Vitest tests and
+ * `it.effect` tests after the value under test has already been produced.
+ *
+ * These helpers throw assertion errors synchronously; they do not run Effects,
+ * provide services, or advance test environments such as `TestClock`. In
+ * Effect-based tests, yield the effect first and then assert on the resulting
+ * value so failures are reported through the surrounding Vitest test.
+ *
  * @since 4.0.0
  */
 import type * as Cause from "effect/Cause"
@@ -17,6 +31,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 +39,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 +49,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 +59,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 +71,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 +84,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 +98,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 +113,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 +123,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 +133,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 +147,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 +157,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 +180,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 +211,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 +221,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 +236,7 @@ export function assertDefined<A>(
 /**
  * Asserts that `a` is `undefined`.
  *
+ * @category testing
  * @since 4.0.0
  */
 export function assertUndefined<A>(
@@ -219,8 +249,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 +267,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 +281,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 +299,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 +313,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>(