28 - Testing Basics

Previous · Next

Tests are the first place Effect’s structured failure model pays off. Every effect produces an Exit<A, E>, a value that encodes success, typed failure, and defects separately.

This step covers the two runners used in tests, the Exit guards that narrow the result, and the patterns for asserting on both success and failure paths.

What you’ll work through

index.test.ts contains three interactive beats — run-promise, run-promise-exit, and exit-guards — each with a stub asking for a runner call or guard. The Exit.match and full-example sections are read-run reference material.

By the end you should reach for runPromiseExit whenever a test inspects a failure, narrow on cause._tag === "Fail" before touching cause.error, and recognise an unhandled-rejection in a test for what it is: a missing exit-returning runner.

Exit Is the Result

Running an effect produces an Exit<A, E>. A throwing runner discards the structure and re-raises the failure; an exit-returning runner hands it back as a value.

1
                         runPromise(effect)
2
   Effect<A, E, never> ──────────────────────► A  (throws on failure)
3

4
                       runPromiseExit(effect)
5
   Effect<A, E, never> ──────────────────────► Exit<A, E>
6
                                                 ├── Success { value: A }
7
                                                 └── Failure { cause: Cause<E> }
8
                                                       ├── Fail      { error: E }
9
                                                       ├── Die       { defect }
10
                                                       └── Interrupt ...

Two runners cover every test:

Runner	Use for
`Effect.runPromise`	Happy path, `await` the success value.
`Effect.runPromiseExit`	Any path, inspect the `Exit` directly.

The test runner in this project is vite-plus/test. In your own project use import { describe, it, expect } from "vitest".

`Effect.runPromise`

Returns Promise<A>. Resolves with the success value; rejects with the failure.

The R channel must be never, every requirement must be satisfied before running.

1
import { Effect } from "effect"
2

3
//      ┌─── Promise<number>
4
//      ▼
5
const result = await Effect.runPromise(Effect.succeed(42))
6
// 42

When to Use

When the test path is expected to succeed. A rejection bubbles up as an unhandled error in the test, which is the right signal, the effect under test failed when it should not have.

> runs. Assertions placed after the `runPromise` call execute against the > pending promise, not the result, and the test passes vacuously.

Your turn await `Effect.runPromise(Effect.succeed(42))` so the test reads `42` from the resolved promise.

`Effect.runPromiseExit`

Returns Promise<Exit<A, E>>. Never rejects.

Use it when you need to assert on a failure, branch on the result, or inspect the typed error.

1
import { Effect, Exit } from "effect"
2

3
class AppError {
4
  readonly _tag = "AppError"
5
  constructor(readonly message: string) {}
6
}
7

8
//      ┌─── Promise<Exit<never, AppError>>
9
//      ▼
10
const exit = await Effect.runPromiseExit(
11
  Effect.fail(new AppError("oops"))
12
)
13

14
if (Exit.isFailure(exit) && exit.cause.reasons[0]?._tag === "Fail") {
15
  exit.cause.reasons[0].error.message // "oops"
16
}

When to Use

When the test asserts on failure, when both branches need verifying, or when the test inspects the specific shape of the error.

Why this matters. runPromiseExit never rejects, so a failing effect stays inside the test as a value. The assertion inspects the typed error instead of fighting an unhandled rejection.

Your turn call `Effect.runPromiseExit` on the failing effect so the test receives an `Exit` value, not a rejection.

`Exit.isSuccess` and `Exit.isFailure`

Type guards that narrow Exit<A, E> into Exit.Success<A, E> or Exit.Failure<A, E>. After the guard, TypeScript exposes .value or .cause directly.

1
import { Effect, Exit } from "effect"
2

3
const exit = await Effect.runPromiseExit(Effect.succeed(42))
4

5
if (Exit.isSuccess(exit)) {
6
  // exit.value: number
7
  exit.value // 42
8
}

Details

exit.cause is a Cause<E>. A cause can be Fail (a typed error from Effect.fail), Die (a defect, usually a bug), or Interrupt.

Always narrow on cause._tag === "Fail" before reading cause.error.

Your turn narrow with `Exit.isSuccess` to read `.value`, then combine `Exit.isFailure` with `cause._tag === "Fail"` to reach `.cause.reasons[0].error`.

`Exit.match`

Branches on success vs failure in a single expression. The onFailure callback receives the full Cause<E>, match on its _tag to distinguish typed errors from defects.

1
import { Effect, Exit } from "effect"
2

3
class NotFound {
4
  readonly _tag = "NotFound"
5
}
6

7
const exit = await Effect.runPromiseExit(Effect.fail(new NotFound()))
8

9
const label = Exit.match(exit, {
10
  onSuccess: (value) => `ok: ${value}`,
11
  onFailure: (cause) =>
12
    cause._tag === "Fail" ? `err: ${cause.error._tag}` : "defect",
13
})
14
// "err: NotFound"

When to Use

When the test computes a string or value from both branches, or when an if/else on _tag would clutter the assertion.

A Full Example

Wrapping an async function with Effect.tryPromise and asserting on both the success and the typed failure.

1
import { Effect, Exit } from "effect"
2

3
class FetchError {
4
  readonly _tag = "FetchError"
5
  constructor(readonly cause: unknown) {}
6
}
7

8
const fetchName = (name: string) =>
9
  Effect.tryPromise({
10
    try: () => Promise.resolve(name),
11
    catch: (cause) => new FetchError(cause),
12
  })
13

14
const value = await Effect.runPromise(fetchName("Alice"))
15
// "Alice"
16

17
const exit = await Effect.runPromiseExit(
18
  Effect.tryPromise({
19
    try: () => Promise.reject(new Error("Network down")),
20
    catch: (cause) => new FetchError(cause),
21
  })
22
)
23

24
if (Exit.isFailure(exit) && exit.cause.reasons[0]?._tag === "Fail") {
25
  exit.cause.reasons[0].error._tag // "FetchError"
26
}

The error in the Exit is the domain FetchError, not the raw Error thrown by the promise. Effect.tryPromise translated it at the boundary; the rest of the program sees the typed value.

Common Pitfalls

1, runPromise on a failure. The promise rejects, which surfaces as an unhandled rejection instead of a structured assertion. Use runPromiseExit whenever the test inspects a failure.

2, Missing await. Both runners return a Promise. Without await the test finishes before the effect runs and assertions inside .then(...) never execute, the test passes vacuously.

3, Reading cause.error without narrowing. A Cause can be Fail, Die, or Interrupt. Only Fail has .error.

Narrow with cause._tag === "Fail" (or use Exit.match) before touching the value.

4, try/catch around runPromise. Catching the rejection back into a try/catch discards the typed error. runPromiseExit is the idiomatic way to inspect failures.

and confirm the resolved value is `42`. - [ ] In the `run-promise-exit` beat, swap in `Effect.runPromiseExit(...)` so the failing effect returns an `Exit` instead of rejecting. - [ ] In the `exit-guards` beat, narrow with `Exit.isSuccess` and the combined `Exit.isFailure && cause._tag === "Fail"` check. - [ ] Read the `Exit.match` and full-example sections — note how the `_tag === "Fail"` narrowing recurs in both forms.

The full test suite

The index.test.ts for this lesson, verbatim from steps/28-testing-basics/.

1
import { describe, it, expect } from "vite-plus/test"
2
import { Effect, Data, Exit } from "effect"
3

4
// =============================================================================
5
// 15 - Testing Basics
6
// =============================================================================
7
//
8
// Two runners cover every test:
9
//   Effect.runPromise      — happy path; rejects on failure.
10
//   Effect.runPromiseExit  — any path; resolves to Exit<A, E>.
11
//
12
// Exit guards (Exit.isSuccess, Exit.isFailure) narrow the result so the
13
// .value or .cause field becomes accessible without an unsafe cast.
14

15
class AppError extends Data.TaggedError("AppError")<{
16
  readonly message: string
17
}> {}
18

19
describe("15 - Testing Basics", () => {
20
  // @beat
21
  //   id: run-promise
22
  //   shape: one-todo
23
  //   title: Run an effect as a Promise
24
  //   teaches: Effect.runPromise resolves with A on success and rejects on failure.
25
  //   hint: await Effect.runPromise(Effect.succeed(42))
26
  describe("Effect.runPromise", () => {
27
    it("resolves with the success value", async () => {
28
      //      ┌─── Promise<number>
29
      //      ▼
30
      const result = await /* @stub */ Effect.runPromise(Effect.succeed(42)) /* @end */
31
      expect(result).toBe(42)
32
    })
33

34
    it("resolves with a value computed inside Effect.gen", async () => {
35
      const result = await Effect.runPromise(
36
        Effect.gen(function* () {
37
          const a = yield* Effect.succeed(10)
38
          const b = yield* Effect.succeed(20)
39
          return a + b
40
        })
41
      )
42
      expect(result).toBe(30)
43
    })
44
  })
45
  // @end-beat
46

47
  // @beat
48
  //   id: run-promise-exit
49
  //   shape: one-todo
50
  //   title: Inspect both branches with Exit
51
  //   teaches: Effect.runPromiseExit resolves to Exit<A, E> and never rejects — failures arrive as values.
52
  //   hint: use Effect.runPromiseExit and then Exit.isFailure(exit)
53
  describe("Effect.runPromiseExit", () => {
54
    it("resolves to a Success exit on a successful effect", async () => {
55
      const exit = await Effect.runPromiseExit(Effect.succeed(1))
56
      expect(Exit.isSuccess(exit)).toBe(true)
57
    })
58

59
    it("resolves to a Failure exit on a failed effect", async () => {
60
      const exit = await /* @stub */ Effect.runPromiseExit(Effect.fail("boom")) /* @end */
61
      expect(Exit.isFailure(exit)).toBe(true)
62
    })
63

64
    it("never rejects — failures arrive as values", async () => {
65
      // runPromise would reject; runPromiseExit always resolves.
66
      const exit = await Effect.runPromiseExit(
67
        Effect.fail(new AppError({ message: "oops" }))
68
      )
69
      expect(exit._tag).toBe("Failure")
70
    })
71
  })
72
  // @end-beat
73

74
  // @beat
75
  //   id: exit-guards
76
  //   shape: multi-todo
77
  //   title: Narrow with Exit.isSuccess and Exit.isFailure
78
  //   teaches: Exit guards narrow the result so .value or .cause is accessible without a cast; for a Fail cause, narrow on cause._tag.
79
  //   hint: combine Exit.isFailure with cause._tag === "Fail" to read cause.error
80
  describe("Exit.isSuccess", () => {
81
    it("narrows the exit so .value is accessible", async () => {
82
      const exit = await Effect.runPromiseExit(Effect.succeed(42))
83

84
      if (/* @stub */ Exit.isSuccess(exit) /* @end */) {
85
        // exit.value: number
86
        expect(exit.value).toBe(42)
87
      } else {
88
        throw new Error("expected a Success exit")
89
      }
90
    })
91
  })
92

93
  describe("Exit.isFailure", () => {
94
    it("narrows the exit so .cause is accessible", async () => {
95
      const exit = await Effect.runPromiseExit(
96
        Effect.fail(new AppError({ message: "oops" }))
97
      )
98

99
      if (/* @stub */ Exit.isFailure(exit) && exit.cause.reasons[0]?._tag === "Fail" /* @end */) {
100
        // exit.cause.reasons[0].error: AppError
101
        expect(exit.cause.reasons[0].error._tag).toBe("AppError")
102
        expect(exit.cause.reasons[0].error.message).toBe("oops")
103
      } else {
104
        throw new Error("expected a Fail cause")
105
      }
106
    })
107
  })
108
  // @end-beat
109

110
  describe("Exit.match", () => {
111
    it("branches on success", async () => {
112
      const exit = await Effect.runPromiseExit(Effect.succeed(10))
113

114
      const label = Exit.match(exit, {
115
        onSuccess: (value) => `ok: ${value}`,
116
        onFailure: () => "err",
117
      })
118

119
      expect(label).toBe("ok: 10")
120
    })
121

122
    it("branches on failure and inspects the typed error", async () => {
123
      const exit = await Effect.runPromiseExit(
124
        Effect.fail(new AppError({ message: "not found" }))
125
      )
126

127
      const label = Exit.match(exit, {
128
        onSuccess: (value) => `ok: ${value}`,
129
        onFailure: (cause) => {
130
          const reason = cause.reasons[0]
131
          return reason?._tag === "Fail" ? `err: ${reason.error.message}` : "defect"
132
        },
133
      })
134

135
      expect(label).toBe("err: not found")
136
    })
137
  })
138

139
  describe("Effect.tryPromise", () => {
140
    it("resolves with the value when the promise resolves", async () => {
141
      const fetchName = () =>
142
        Effect.tryPromise({
143
          try: () => Promise.resolve("Alice"),
144
          catch: (cause) => new AppError({ message: String(cause) }),
145
        })
146

147
      const result = await Effect.runPromise(fetchName())
148
      expect(result).toBe("Alice")
149
    })
150

151
    it("places a rejection into the typed E channel", async () => {
152
      const exit = await Effect.runPromiseExit(
153
        Effect.tryPromise({
154
          try: () => Promise.reject(new Error("Network down")),
155
          catch: (cause) => new AppError({ message: `Fetch failed: ${cause}` }),
156
        })
157
      )
158

159
      if (Exit.isFailure(exit) && exit.cause.reasons[0]?._tag === "Fail") {
160
        expect(exit.cause.reasons[0].error._tag).toBe("AppError")
161
        expect(exit.cause.reasons[0].error.message).toContain("Network down")
162
      } else {
163
        throw new Error("expected a Fail cause")
164
      }
165
    })
166
  })
167
})

05·01Testing Basics

28 - Testing Basics

What you’ll work through

Exit Is the Result

`Effect.runPromise`

`Effect.runPromiseExit`

`Exit.isSuccess` and `Exit.isFailure`

`Exit.match`

A Full Example

Common Pitfalls

See Also

The full test suite