@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 07:15 UTC

main
md 197 lines 11 KB
Rendered Raw
1 # Testing
2
3 ## Stories: specify the model
4
5 A story is given/when/then over the real model, in memory. Policies, sagas and projections run for real. External system calls wait until the story answers them, and a clock you control stamps commands. A story fails on any event, rejection, external call or saga defect it doesn't account for, so a passing story has accounted for every outcome.
6
7 ```ts
8 // packages/domain/test/Bank.story.test.ts
9 import { it } from "@effect/vitest";
10 import { Story } from "@alchemy.run/domain/Story";
11 import * as Layer from "effect/Layer";
12 import { Account } from "../src/Account/Account.aggregate.ts";
13 import { MoneyDeposited } from "../src/Account/DepositMoney.command.ts";
14 import { AccountOpened } from "../src/Account/OpenAccount.command.ts";
15 import { InsufficientFunds } from "../src/Account/InsufficientFunds.rejection.ts";
16 import { MoneyWithdrawn, WithdrawMoney } from "../src/Account/WithdrawMoney.command.ts";
17 import { customer } from "../src/Actor.ts";
18 import { Bank, BankHandlers } from "../src/Bank.model.ts";
19 import { CurrentActor } from "../src/CurrentActor.context.ts";
20 import { CustomerId } from "../src/Customer/Customer.id.ts";
21 import { FraudCheck } from "../src/Fraud/FraudCheck.external.ts";
22 import { MemoryLedgerStore } from "../src/Ledger/LedgerStore.ts";
23 import { Payments } from "../src/Settlement/Payments.external.ts";
24
25 const story = Story.make(Bank, {
26 layer: BankHandlers.pipe(Layer.provide(MemoryLedgerStore)), // required when the model has handlers
27 stub: [FraudCheck, Payments], // faked: the story answers each call
28 });
29 const a1 = Account.ref("a-1");
30
31 it.effect("withdraws within the balance, and refuses beyond it", () =>
32 story(
33 Story.given(a1, new AccountOpened({ customerId: CustomerId.make("c-1"), owner: "sam" }),
34 new MoneyDeposited({ amount: 100, balanceAfter: 100 })),
35 Story.provide(CurrentActor, customer("c-1")), // what the command's middleware would provide
36 Story.when(a1, new WithdrawMoney({ amount: 30 })),
37 Story.then(a1, new MoneyWithdrawn({ amount: 30, balanceAfter: 70 })),
38 Story.replied({ balance: 70 }),
39 Story.when(a1, new WithdrawMoney({ amount: 100 })),
40 Story.rejected(new InsufficientFunds({ balance: 70, requested: 100 })),
41 ),
42 );
43 ```
44
45 The steps:
46
47 - `given(ref, ...events)` records history. It reaches views, but never triggers policies.
48 - `when(ref, command)` sends a command, then runs every policy, saga and projection until the model settles.
49 - `then(ref, ...events)` asserts the next events committed on that stream, since the last `then` or `given` on it. With no events, it asserts that nothing new was committed. Every committed event needs a `then`, on every stream, including those a policy or saga writes: an event no `then` asserts fails the story at the end.
50 - `rejected(rejection)` asserts the last command's rejection. An unasserted rejection fails the story.
51 - `replied(value)` asserts the last command's reply.
52 - `state(ref, partial | fn)` asserts aggregate state.
53 - `view(View, ref, partial | fn | Story.none)` asserts view state. `emitted(View, ref, [...])` asserts a view's emitted events, and `streamed(Stream, ref, ...)` a stream's entries.
54 - `provide(Service, value)` stands in for middleware on the commands that follow.
55 - `clock("2026-01-02T09:00:00Z")` moves time: commands are stamped with it, and scheduled commands and saga sleeps that are now due fire. It also takes epoch milliseconds or a `DateTime`. It only moves forward: a time before the current one fails the story, unless only `provide` steps ran before it.
56 - `advance("1 day")` moves the clock forward by a duration (any `Duration.Input`) instead of to a time.
57
58 The steps type-check against the last `when`: `rejected` takes only a rejection its command declares in `rejects`, and `replied` only its reply type. A `when` type-checks only after a `provide` for every service its command's middleware provides. A helper typed as plain `Step` turns these checks off until the next `when`, so let helpers infer their return type.
59
60 More: [Testing models](https://alchemy.run/domain/testing-models), [Story](https://alchemy.run/domain/story).
61
62 ### External system calls
63
64 ```ts
65 Story.call(FraudCheck.score, { accountId: a1.id }), // a matching call is waiting (partial args)
66 Story.succeed(FraudCheck.score, { risk: 0.95 }), // answers the only waiting call to score
67 ```
68
69 When several calls are waiting, tag each one as you expect it, and answer it by tag. A tag names the earliest matching call, in the order calls were made:
70
71 ```ts
72 Story.call("a-1", FraudCheck.score, { accountId: a1.id }),
73 Story.call("a-2", FraudCheck.score, { accountId: a2.id }),
74 Story.succeed("a-2", FraudCheck.score, { risk: 0.1 }),
75 Story.succeed("a-1", FraudCheck.score, { risk: 0.95 }),
76 ```
77
78 An answer is checked against the operation's schemas like an adapter's, so a `succeed` or `fail` value the schema rejects fails the policy. Every call needs a `call` step before it's answered; each one matches a single call, earliest first. An untagged `succeed` with several calls waiting fails the story, and so does a call left unanswered at the end.
79
80 `fail` answers a waiting call with the operation's declared `error:`, to test the branch where the vendor refuses. `die` answers it with a defect, as when the transport breaks. Both find the call the way `succeed` does, untagged or by tag, and only a declared error type-checks (any one of them, when the operation lists several):
81
82 ```ts
83 Story.call(Payments.refund, { settlementId: "st_1" }),
84 Story.fail(Payments.refund, new RefundDeclined({ reason: "card-closed" })),
85 Story.call("r-2", Payments.refund, { settlementId: "st_2" }),
86 Story.die("r-2", Payments.refund, new Error("socket closed")),
87 ```
88
89 More: [Testing models: Answer outside systems](https://alchemy.run/domain/testing-models#answer-outside-systems).
90
91 ### Real calls
92
93 A system left out of `stub` is called for real through its adapter Layer, which you provide to the story (its type requires it). The story records each call: a `call` step checks what it was sent and must come first, and `returned` / `failed` / `died` check how it ended, found like `succeed`. A real call no step asserts fails the story, and the story waits for real calls to finish before each step.
94
95 ```ts
96 const story = Story.make(Bank, { layer: BankHandlers, stub: [FraudCheck] }); // Payments runs for real
97
98 story(
99 Story.when(account, new RecordSettlement({ settlementId: "st_1", amount: 500 })),
100 Story.call(Payments.refund, { settlementId: "st_1", amount: 500 }),
101 Story.returned(Payments.refund, { refundId: "re_st_1" }),
102 ).pipe(Effect.provide(StripePayments));
103 ```
104
105 More: [Testing models: Assert real calls](https://alchemy.run/domain/testing-models#assert-real-calls).
106
107 ### Every adapter, same tests
108
109 An adapter is a Layer for the system's service. Run one set of tests against each adapter (vendor, in-memory fake, no-op) so a fake never drifts from the vendor:
110
111 ```ts
112 for (const [adapter, layer] of [["Twilio", TwilioSms], ["fake", FakeSms]] as const) {
113 describe(`Sms: ${adapter}`, () => {
114 it.effect("counts the segments", () =>
115 Effect.gen(function* () {
116 const sms = yield* Sms;
117 const sent = yield* sms.send({ to: "+15550100", body: "x".repeat(200) });
118 expect(sent.segments).toBe(2);
119 }).pipe(Effect.provide(layer)),
120 );
121 });
122 }
123 ```
124
125 More: [Testing models: Run the same tests against every adapter](https://alchemy.run/domain/testing-models#run-the-same-tests-against-every-adapter).
126
127 ### Sagas
128
129 Test what a saga does: the events its steps record on aggregates, and how the run ended. Don't test its internal steps.
130
131 ```ts
132 Story.then(a1, new TransferDebited({ ... }), new TransferRefunded({ ... })), // the compensation ran
133 Story.saga(ExecuteTransfer, t1, { _tag: "Rejected", rejection: new DestinationClosed() }),
134 Story.saga(ExecuteTransfer, t1, { _tag: "Running" }),
135 Story.signal(ExecuteTransfer, t1, Decision, "approved"), // complete a DurableDeferred it waits on
136 ```
137
138 The statuses are `NotStarted`, `Running`, `Completed`, `Rejected`, `Interrupted` and `Died`. A run that dies fails the story unless a step asserts `{ _tag: "Died" }`.
139
140 More: [Saga: Test it](https://alchemy.run/domain/saga#test-it).
141
142 ### The declaration
143
144 `Domain.verify(Model)` returns every definition problem that would fail the model's Layer build (missing `keyOf`, view `state` without `initial`, a policy or projection `on` an event no source emits, a stream with two writers, duplicate names). Keep one test that expects it to be empty:
145
146 ```ts
147 it("the model is well defined", () => expect(Domain.verify(Bank)).toEqual([]));
148 ```
149
150 More: [Domain Model: Check the declaration](https://alchemy.run/domain/model#check-the-declaration).
151
152 ### What to cover
153
154 For every command, cover the happy path, each rejection, and each authorization case (owner, other customer, agent). For every policy, cover the reaction, the reaction when its command is rejected, and the reaction when an external call fails with its declared error. For every saga, cover completion, each failure with its compensation, and each wait (signal, timeout via `clock`). For every view, check its state after the events it folds.
155
156 More: [Testing models: Check every outcome](https://alchemy.run/domain/testing-models#check-every-outcome).
157
158 ## Api tests: the client's view
159
160 In the server package, host the model in memory with the real middleware, and drive it through the Api client. This checks authentication, `validate`, and live reads.
161
162 ```ts
163 // packages/server/test/CustomerApi.test.ts
164 const Ports = Layer.mergeAll(SiftFraudCheck, StripePayments, MemoryLedgerStore);
165 const BankInMemory = Bank.layer(BankHandlers).pipe(Layer.provide(Layer.mergeAll(Ports, Domain.InMemory)));
166 const World = Layer.mergeAll(SessionLive, MfaChallengeLive).pipe(Layer.provideMerge(BankInMemory));
167
168 const asCustomer = (id: string) =>
169 CustomerApi.clientInProcess.pipe(Effect.provide(sessionClient(`customer:${id}`)));
170
171 it.live("only the owner may withdraw", () =>
172 Effect.gen(function* () {
173 const sam = yield* asCustomer("c-1");
174 const deposited = yield* sam.DepositMoney(accountId, { amount: 250 });
175 // deposited: { reply: { balance: 250 }, stream: "Account/...", version: 2 }
176 const alex = yield* asCustomer("c-2");
177 const refused = yield* alex.WithdrawMoney(accountId, { amount: 10 }, mfa).pipe(Effect.flip);
178 expect(refused._tag).toBe("NotOwner");
179 }).pipe(Effect.scoped, Effect.provide(World)),
180 );
181 ```
182
183 `clientInProcess` talks to the in-memory host directly. Use `Domain.protocolHttp` with a local HTTP server to cover the wire too.
184
185 More: [Testing an Api](https://alchemy.run/domain/testing-apis).
186
187 ## Integration: the deployed stack
188
189 At the root, deploy `alchemy.run.ts` with `@alchemy.run/test/Bun` and drive the deployed Api over HTTP and WebSocket. Keep it to one end-to-end flow. Stories carry the behavior.
190
191 More: [Testing an Api: Test a deployment](https://alchemy.run/domain/testing-apis#test-a-deployment).
192
193 ## Commands
194
195 - Domain package: `pnpm --filter @acme/domain test` (vitest).
196 - Monorepo type-check: `tsc -b`.
197 - Integration: `bun test test/integ.test.ts`, with cloud credentials.