feat: add it.*.fails method to @effect/vitest (#3973)

Co-authored-by: Tim <hello@timsmart.co>

Author: lishaduck

.changeset/cyan-pans-tan.md

@@ -0,0 +1,5 @@
+---
+"@effect/vitest": patch
+---
+
+Add it.*.fails method to @effect/vitest

.vscode/settings.json

@@ -2,6 +2,8 @@
   "typescript.tsdk": "node_modules/typescript/lib",
   "typescript.preferences.importModuleSpecifier": "relative",
   "typescript.enablePromptUseWorkspaceTsdk": true,
+  "deno.enable": false,
+  "biome.enabled": false,
   "editor.formatOnSave": true,
   "eslint.format.enable": true,
   "[json]": {

packages/vitest/README.md

@@ -212,6 +212,30 @@ it.effect.only("test failure as Exit", () =>
 )
 ```
 
+## Expecting Tests to Fail
+
+When adding new failing tests, you might not be able to fix them right away. Instead of skipping them, you may want to assert it fails, so that when you fix them, you'll know and can re-enable them before it regresses.
+
+**Example** (Asserting one test fails)
+
+```ts
+import { it } from "@effect/vitest"
+import { Effect, Exit } from "effect"
+
+function divide(a: number, b: number): number {
+  if (b === 0) return Effect.fail("Cannot divide by zero")
+  return Effect.succeed(a / b)
+}
+
+// Temporarily assert that the test for dividing by zero fails.
+it.effect.fails("dividing by zero special cases", ({ expect }) =>
+  Effect.gen(function* () {
+    const result = yield* Effect.exit(divide(4, 0))
+    expect(result).toStrictEqual(0)
+  })
+)
+```
+
 ## Logging
 
 By default, `it.effect` suppresses log output, which can be useful for keeping test results clean. However, if you want to enable logging during tests, you can use `it.live` or provide a custom logger to control the output.

packages/vitest/src/index.ts

@@ -56,6 +56,7 @@ export namespace Vitest {
     each: <T>(
       cases: ReadonlyArray<T>
     ) => <A, E>(name: string, self: TestFunction<A, E, R, Array<T>>, timeout?: number | V.TestOptions) => void
+    fails: Vitest.Test<R>
 
     /**
      * @since 1.0.0

packages/vitest/src/internal.ts

@@ -99,6 +99,9 @@ const makeTester = <R>(
       (args, ctx) => run(ctx, [args], self) as any
     )
 
+  const fails: Vitest.Vitest.Tester<R>["fails"] = (name, self, timeout) =>
+    V.it.fails(name, (ctx) => run(ctx, [ctx], self), timeout)
+
   const prop: Vitest.Vitest.Tester<R>["prop"] = (name, arbitraries, self, timeout) => {
     if (Array.isArray(arbitraries)) {
       const arbs = arbitraries.map((arbitrary) => Schema.isSchema(arbitrary) ? Arbitrary.make(arbitrary) : arbitrary)
@@ -136,7 +139,7 @@ const makeTester = <R>(
     )
   }
 
-  return Object.assign(f, { skip, skipIf, runIf, only, each, prop })
+  return Object.assign(f, { skip, skipIf, runIf, only, each, fails, prop })
 }
 
 export const prop: Vitest.Vitest.Methods["prop"] = (name, arbitraries, self, timeout) => {

packages/vitest/test/index.test.ts

@@ -68,7 +68,7 @@ it.effect.runIf(false)("effect runIf (false)", () => Effect.die("not run anyway"
 
 // The following test is expected to fail because it simulates a test timeout.
 // Be aware that eventual "failure" of the test is only logged out.
-it.scopedLive("interrupts on timeout", (ctx) =>
+it.scopedLive.fails("interrupts on timeout", (ctx) =>
   Effect.gen(function*() {
     let acquired = false
 
@@ -84,7 +84,7 @@ it.scopedLive("interrupts on timeout", (ctx) =>
       () => Effect.sync(() => acquired = false)
     )
     yield* Effect.sleep(1000)
-  }), { timeout: 100, fails: true })
+  }), 1)
 
 class Foo extends Context.Tag("Foo")<Foo, "foo">() {
   static Live = Layer.succeed(Foo, "foo")