AGENT SKILL

effect-v4-testing

Use when writing, reviewing, or fixing tests for Effect v4 code with @effect/vitest — it.effect + Effect.gen as the default runner, asserting typed errors via Effect.flip or Effect.result (Exit + Cause for defects), providing test/mock layers with layer(...) for any service in R (owned or consumed), fault-injecting one method of a real layer, property tests with it.effect.prop over a Schema, TestClock for time-dependent logic, converting a plain-Vitest repo, and the mutate-the-edges discipline for proving a suite can actually fail — the discriminating input wrong in exactly one way, per-clause and per-path mutation, and the positive control a "nothing found" result needs before it's believed.

License 许可
MIT
最近更新
2026-11-14
Stars
★ 8
Forks
2

01 前言 Front Matter

name
effect-v4-testing
targets
{ "copilot": { "description": "Use when writing, reviewing, or fixing tests for Effect v4 code with @effect/vitest — it.effect + Effect.gen as the default runner, asserting typed errors via Effect.flip or Effect.result (Exit + Cause for defects), providing test/mock layers with layer(...) for any service in R (owned or consumed), fault-injecting one method of a real layer, property tests with it.effect.prop over a Schema, TestClock for time-dependent logic, converting a plain-Vitest repo, and the mutate-the-edges discipline for proving a suite can actually fail — the discriminating input wrong in exactly one way, per-clause and per-path mutation, and the positive control a \"nothing found\" result needs before it's believed. Also triggers on: Tests: 0/0 passed lying while the exit code is honest, TestClock at the epoch (1970), layer() memoizing while Effect.provide does not, TestConsole swallowing Effect.log* through ConsoleRef, vi.mock must import vi from vitest, structural checks over source text." } }
description
Use when writing, reviewing, or fixing tests for Effect v4 code with @effect/vitest — it.effect + Effect.gen as the default runner, asserting typed errors via Effect.flip or Effect.result (Exit + Cause for defects), providing test/mock layers with layer(...) for any service in R (owned or consumed), fault-injecting one method of a real layer, property tests with it.effect.prop over a Schema, TestClock for time-dependent logic, converting a plain-Vitest repo, and the mutate-the-edges discipline for proving a suite can actually fail — the discriminating input wrong in exactly one way, per-clause and per-path mutation, and the positive control a "nothing found" result needs before it's believed.
when_to_use
it.scoped removed, Arbitrary size clamp/-0/exhaustion/dropped-regex traps, Path.layer + @effected/memfs need no platform package, vi.mock must import vi from vitest, layer() memoizing while Effect.provide does not, TestConsole swallowing Effect.log* through ConsoleRef, a small real delay hanging the virtual clock, Tests: 0/0 passed lying while the exit code is honest, a project-filtered run from inside a package not loading the root config, TestClock starting at the epoch (1970), an eagerly-recording layerNoop stub, a narrowing if with no else branch, structural checks over source text (import walkers, export assertions, comment strippers), the two-latch rule for concurrency-leak tests, unhandledErrors and a stray process.exitCode making a green suite lie

02 资源文件 13

03 SKILL.md 正文

Effect v4 testing with @effect/vitest

@effect/vitest re-exports Vitest, so it is the single entrypoint for test APIs — with one exception (vi.mock, below). Effect programs run through it.effect, never through a bare it() that calls Effect.runSync/ runPromise. Our house test files (packages/jsonc/__test__/Jsonc.test.ts, packages/yaml/__test__/Yaml.test.ts) are the canonical shapes. (The effect/testing/* modules — TestClock, TestConsole, TestSchema — and the property engine Arbitrary are indexed in effect-v4-module-index; this skill owns how to use them. There is no FastCheck module.)

Migrating a plain-Vitest Effect repo? Adopt @effect/vitest. A repo whose tests are plain Vitest is not "nothing to migrate on the testing axis": add @effect/vitest and route Effect-returning tests through it.effect. The conversion has its own traps → references/migrating-a-repo.md.

Testing a specific front end or a repo-shape check routes elsewhere first. This skill owns the general @effect/vitest mechanics; a front end's own testing subpath owns the rest: testing a CLI bin → effect-v4-cli (CliTest); an Ink screen, a wizard or a live view → effect-v4-cli (CliUiTest: its session transcript, and its snapshot serializer registered through Vitest's snapshotSerializers config, snapshots being the one place a test needs expect); testing an MCP server → effect-v4-mcp (McpHarness, McpProbe); a monorepo's own repo-shape checks (layering, source boundaries, packed installs) → @effected/workspaces/testing (see effected-packages).

Install it from the same catalog as effect, so it resolves to the same version — never bare and never from a dist-tag. Effect releases effect and every @effect/* package together at one shared version, so @effect/vitest must resolve to exactly the version effect does. A dist-tag (latest, beta, rc, snapshot) is a moving pointer that can resolve to a version other than the one effect resolves to.

The failure of a mismatch names neither package: a v3 @effect/vitest installed beside v4 effect loads with only a one-line Issues with peer dependencies found warning; pnpm peers check then lists unmet effect ^3 and vitest ^3 peers, and the test file fails to load with Cannot find module '…/effect/dist/Arbitrary.js', because the v3 package imports a module the v4 effect does not ship. It reads as a broken install rather than a version mismatch. Run pnpm peers check and compare @effect/vitest's resolved version with effect's in the lockfile before believing any resolution. With @effected/pnpm-plugin-effected the dependency comes from catalog:effected, which carries both at the same range.

vi.mock is the one import that must NOT come from @effect/vitest. Vitest hoists it above all imports, so a vi bound through the re-export is not yet initialized and the file dies at load with Cannot access '__vi_import_1__' before initialization — naming neither vi nor @effect/vitest. Write import { vi } from "vitest" in any file calling vi.mock; vi.fn / vi.spyOn work fine through the re-export (measured across 24 files).

A spy restored in try/finally inside Effect.gen LEAKS. A failing assertion leaves through the error channel, so the finally does not run the way the shape suggests, and a vi.spyOn on a process global that outlives its test poisons its neighbours — false reds first, false greens later. Acquire and release spies with Effect.acquireUseRelease instead → references/false-greens.md.

A repo without @effect/vitest can still test Effect code: a plain Vitest it calling a small Effect.runPromise helper. What it loses is what it.effect installs: a per-test Scope and the virtual TestClock and TestConsole (Effect.scoped and TestClock.layer() add the scope and the clock back by hand), plus layer(...) sharing and it.effect.prop. The skill's it.effect examples assume the package is installed.

The default runner: it.effect + Effect.gen

import { assert, describe, it } from "@effect/vitest";
import { Jsonc } from "@effected/jsonc";
import { Effect } from "effect";

describe("Jsonc", () => {
  it.effect("parses objects, arrays and scalars", () =>
    Effect.gen(function* () {
      const value = yield* Jsonc.parse('{ "a": 1 }');
      assert.deepStrictEqual(value, { a: 1 });
    }),
  );
});
  • it.effect runs the returned Effect and provides the default test environment — TestEnv = Layer.mergeAll(TestConsole.layer, TestClock.layer()) (packages/vitest/src/internal/internal.ts:68), piped through flow(Effect.scoped, Effect.provide(TestEnv)) (internal.ts:490). Its type is Tester<R | Scope.Scope>, so scoped effects (Effect.acquireRelease, scoped layers) run directly under it.effect.

  • There is no it.scoped (zero scoped matches in packages/vitest/src/index.ts; the v3→v4 migration guide spells the replacement out — it.scoped(...) becomes it.effect(...), it.scopedLive(...) becomes it.live(...)). The Tester surface is skip/skipIf/runIf/only/each/fails/prop — it.effect.skipIf and it.effect.runIf exist and are well-typed (packages/vitest/src/index.ts:82-83); reach for them instead of hand-rolling a conditional describe.

  • it.live (Tester<Scope.Scope | R>) opts into the real Clock and live runtime services. Use only when a test genuinely needs wall-clock behavior.

  • it.effect takes a Vitest timeout as its third argument — it.effect(name, self, timeout?: number | TestOptions). Any real-time elapsed assertion above Vitest's 5000ms default is dead code without it (see references/false-greens.md).

  • Never it("...", () => Effect.runPromise(program)). Plain it() is fine only for genuinely non-Effect pure code (Jsonc.stripComments, Yaml.equals).

  • The rule is UNCONDITIONAL. "But the layer is fully synchronous" is not a carve-out. The tempting shape is a describe block with a local const validate = (doc) => Effect.runSync(Effect.provide(program, Svc.layer)) helper, justified because the service's implementation happens to be synchronous (a Layer.succeed over a sync engine such as ajv). It shipped in packages/schemastore/__test__/schema-validator.test.ts, alongside four sibling blocks in the same file that use layer(...) + it.effect correctly. Synchrony is a property of today's implementation, never of the contract: the member's type is Effect<A, E>, which permits async, and nothing in the type system tells you when that changes. The two costs:

    • Swap one member for an async implementation and every test in the block dies at runtime with AsyncFiberError: An asynchronous Effect was executed with Effect.runSync — no type error, no warning, and the blast radius is the whole describe.
    • A typed failure escapes runSync as a throw (in v4 the error instance itself, _tag intact — not a wrapper), so it lands in Vitest's generic exception path instead of Effect.flip / Effect.result, and the test asserts on a stack trace instead of the error channel.

    The correct shape costs one line: layer(Svc.layer)("the shipped engine", (it) => { it.effect(…, () => Effect.gen(…)) }) — and it gets you TestClock/TestConsole and layer memoization for free.

  • Never it("...", () => Effect.gen(...)) either — the inverse mistake, and the worse one. Returning an Effect without running it hands Vitest a non-promise it does nothing with: the test reports green having evaluated zero assertions. The two shapes are inverses and only the first one looks wrong:

    shape runs? symptom
    it(..., () => Effect.runPromise(p)) yes correct result, execution laundered
    it(..., () => p) no always green, no assertion ever evaluated

    The fix in both directions is it.effect. This shipped in @effected/schemastore and was caught only in review — and the vacuous test was the one cited as proof to a downstream consumer who had reported the very finding it failed to pin. A false green does not merely miss a regression; it gets used as evidence. The shape is greppable, so it belongs in a structural check (see references/structural-checks.md).

  • Never launder an Effect into a fixture with Effect.runSync. If a test input comes from an Effect (a parse, a decode), the test is an it.effect and you yield* it; if you only need a domain value, build it with X.make.

  • yield* import(...) breaks — it throws (intermediate value) is not iterable, naming neither the import nor the yield. A dynamic import inside Effect.gen is yield* Effect.promise(() => import("./thing.js")); a bulk await → yield* rewrite produces the broken form mechanically.

Asserting on typed errors

A test for the failure channel must not let the error escape as a defect. Effect.flip — swaps channels so the typed error becomes the success value — is our house pattern:

import { assert, it } from "@effect/vitest";
import { Jsonc } from "@effected/jsonc";
import { Effect } from "effect";

it.effect("fails with an aggregate JsoncParseError", () =>
  Effect.gen(function* () {
    const error = yield* Effect.flip(Jsonc.parse("{ bad }"));
    assert.strictEqual(error._tag, "JsoncParseError");
    assert.isAbove(error.errors.length, 0);
  }),
);

Effect.result — never fails; returns a Result you narrow with Result.isSuccess/isFailure (the v4 replacement for the removed Either). Reach for it when one program must assert on both channels. Effect.exit — the full Exit (defects and interrupts included) when you must inspect a Cause. Signatures (verified): flip: Effect<A,E,R> => Effect<E,A,R>, result: … => Effect<Result<A,E>,never,R>, exit: … => Effect<Exit<A,E>,never,R>.

Effect.flip is WRONG for a defect. It swaps only the typed channel, so a defect escapes it and the test errors instead of asserting. Defects go through Effect.exit, with an explicit throw/fail on the non-failure branch:

import { assert, it } from "@effect/vitest";
import { Cause, Effect, Exit } from "effect";

const subject = Effect.die(new Error("the expected message"))

it.effect("the subject dies with the expected message", () =>
  Effect.gen(function* () {
    const exit = yield* Effect.exit(subject);
    if (Exit.isFailure(exit)) {
      assert.include(Cause.pretty(exit.cause), "the expected message");
    } else {
      assert.fail("expected a defect, but the effect succeeded");
    }
  }),
);

A narrowing if with no else asserts nothing on the other path. A bare if (Exit.isFailure(exit)) { …assert… } passes silently on success — found six separate times in one package's suite. It is its own anti-pattern, not an Exit-specific one.

Genuine defects must NOT be swallowed into the typed channel — the half a flip-based test cannot prove. Assert Effect.exit, that the cause holds no Fail reason (the discriminating line), and that the Die defect is the ORIGINAL error. Assert helpers are never type predicates — narrow with a real if; and assert.deepStrictEqual against literal-typed encodes needs an explicit <unknown> type argument. Worked example and both traps → references/asserting-errors.md.

Providing test / mock layers

layer(...) applies to any service in a test's R — owned or consumed. Its signature takes any Layer.Layer<R, E>; nothing requires the package under test to declare the service. A package that owns no services but consumes Path.Path or FileSystem.FileSystem needs suite-boundary layers most.

import { assert, describe, layer } from "@effect/vitest";
import { Context, Effect, Layer } from "effect";

class Foo extends Context.Service<Foo, string>()("Foo") {
  static readonly layer = Layer.succeed(Foo, "foo");
}

describe("foo", () => {
  layer(Foo.layer)((it) => {
    it.effect("gets foo", () =>
      Effect.gen(function* () { assert.strictEqual(yield* Foo, "foo"); }));
  });
});

layer() memoizes; plain Effect.provide does NOT. That asymmetry is the whole decision

The top-level layer builds once per group and keeps the scope open until afterAll; a per-test .pipe(Effect.provide(L)) rebuilds per test. Nested provides inside one running effect memoize constituent consts by reference, so a fault-injected variant can silently fall back to the REAL services already built outside.

Per-test provide is the SAFE default; collapsing a suite onto a suite-boundary layer() is the RISKY move. Build-once means every stateful resource is cumulative across the group — TestClock.adjust, in-memory stores, TTL expiry, TestConsole.logLines — so a clock-driving test must NOT live inside a layer() block. Pre-flight before collapsing, the nested-layer and excludeTestServices forms, and why MethodsNonLive has no .live → references/providing-layers.md; worked failures in references/migrating-a-repo.md. A mock service is a Context.Service with a test Layer, swapped Live → Test at this boundary, never inside test bodies.

Testing a boundary-tier package that does real IO needs no platform package. Path.layer comes from effect core (Path.ts:931) and is the POSIX Path only (/ separator, POSIX semantics): provide it in tests, never in code under src/, where it would give Windows users POSIX paths. The filesystem double is @effected/memfs, a pure package with no node:* import — core ships no FileSystem.layer, only the deny-by-default layerNoop (FileSystem.ts:848), which is not a double (references/providing-layers.md). So @effected/walker tests filesystem behavior with zero @effect/platform-node devDependency:

import { MemoryFileSystem } from "@effected/memfs";
import { assert, layer } from "@effect/vitest";
import { Effect, FileSystem, Layer, Path } from "effect";

layer(Path.layer)("path ops", (it) => {
  it.effect("Path is in R, no Effect.provide in the body", () =>
    Effect.gen(function* () {
      const path = yield* Path.Path;
      assert.strictEqual(path.dirname("/a/b"), "/a");
    }));
});

const Volume = Layer.merge(Path.layer, MemoryFileSystem.layerWith({ "/a/.rc": "" }));

layer(Volume)("seeded filesystem", (it) => {
  it.effect("fs.exists consults the volume", () =>
    Effect.gen(function* () {
      const fs = yield* FileSystem.FileSystem;
      assert.isTrue(yield* fs.exists("/a/.rc"));
      assert.isFalse(yield* fs.exists("/a/other"));
    }));
});

layerNoop's unstubbed members answer in THREE different ways (makeNoop (FileSystem.ts:712) splits them) — typed NotFound, silent success (exists → false, remove → Effect.void), and Effect.die (makeDirectory, makeTemp*), which Effect.catch cannot absorb. None of this is a reason to stub layerNoop better — it is the argument for @effected/memfs. This repo's rule: a FileSystem double is @effected/memfs, never a layerNoop stub and never a hand-rolled node:fs port stub. The one exception is an oracle test that runs a third-party engine (the tool your code mirrors, such as @changesets/apply-release-plan or a package manager) on the same input as your code: the engine reads node:fs and real git itself, where no volume can reach it. Copy the fixture into a temporary directory, run both sides there over @effect/platform-node, and keep every other test on memfs. Every Effect.provide of a memfs layer re-seeds a fresh volume, so assert inside the one provide or provide a pinned handle.layer. The table, the BOM trap, the seed forms and the one-layer(...)-block-per-fixture shape → references/providing-layers.md; picking the memfs form, seeds, faults, case-insensitive volumes and traps → references/memfs.md.

A service built on @effected/store is tested over its REAL implementation, never a hand-written double: share one implementation effect written against Store between layer(filename) (production, Store.layerSqlite) and a layerMemory() FACTORY over Store.layerTest({ migrations }), which opens a fresh migrated :memory: database per build. A factory, not a const, so two consumers in one composed graph never share a database by reference memoization. Pair it with @effected/memfs for a fully hermetic pipeline. An application wired through @effected/app tests over AppTest.layer(options) from @effected/app/testing — fixed XDG paths, :memory: Store/Cache and a memfs volume, R = never; @effected/memfs is that subpath's optional peer, so add it as a devDependency.

Every stub effect goes through Effect.suspend. A recorder that pushes eagerly logs calls that never executed. Worked probe → references/false-greens.md.

Faulting ONE method of a real layer

For "behaves like the real service except this one method fails on demand", layerNoop is the wrong tool. The house recipe is Layer.effect + spread the base + Layer.provide(base), with Layer.updateService as the shorter form and Layer.mock for partial stubs that die loudly. Full scaffold, the source anchors and the three ways to get the spread wrong → references/fault-injection.md.

The env seam: swap ConfigProvider, never process.env

Code reading its environment through Config.* already has a test seam, and it is not in R: ConfigProvider.ConfigProvider is a Context.Reference, so a test replaces it with Effect.provide(ConfigProvider.layer(ConfigProvider.fromEnv({ env: record }))). An empty record is the "variable unset" case; the default provider would answer from whatever the developer's shell exports. Never mutate process.env in beforeEach. Worked example → references/env-seam.md.

Property testing with it.effect.prop and it.prop

Feed a Schema (or class) directly as an arbitrary. The engine is core's native Arbitrary, not fast-check — there is no FastCheck module, and no fastCheck: { numRuns } option: the bag is arbitrary: { runs, size, … }. The traps a probe settled, each with its fix in references/property-testing.md:

  • The size clamp (default 10) silently shrinks a domain — pass size: <cap> for long-input properties.
  • A brand whose check is a bare makeFilter EXHAUSTS instead of hanging.
  • The generator emits -0; round-trip properties over serialized numbers exclude it.
  • A partial dictionary is a Struct of optionalKey, not a Record.
  • isPattern regexes must be lookaround-free, free of i/m/v, and carry u; otherwise the pattern is silently dropped.
  • A custom-alphabet string is Arbitrary.array over a Schema.Literals of characters, mapped through join(""); Arbitrary.array is under the same size clamp.
  • Reading a failure: the agent reporter compacts it to one line; the full shrunk input and replay token are in the --reporter=json output file. Pin the counterexample as an ordinary regression test.

Time-dependent logic: TestClock

it.effect ALWAYS installs a virtual TestClock. This is not opt-in.

  • A small REAL delay anywhere under the test — usually in src — hangs to the vitest timeout with no message pointing at the clock. Any Effect.sleep, retry schedule, timeout or polling interval needs a driven clock or it.live; grep the implementation, not only the test. A test that hangs for exactly five seconds: suspect wall-clock time first.
  • It starts at the EPOCH, so clock reads return 1970 — set the clock with TestClock.setTime(...) whenever the code under test reads time.
  • Real async I/O interleaved with sleeps desyncs the drain loop — use it.live for exactly those tests, outside the layer() block.
  • Do not manually provide TestClock.layer() under it.effect, and never call TestClock.adjust under it.live.
  • Stage an interleaving with latches, not sleeps, and a leak test needs two latches.

The grep pattern, the driving example, the clock-free interrupt restructure and the source-visible reasoning → references/testclock.md; the two-latch probe → references/false-greens.md.

it.effect also intercepts CONSOLE output — including Effect.log*

TestEnv installs TestConsole alongside the clock, so a spy on the real console.log captures nothing — and auditing for Console.* call sites is insufficient, because Effect's default logger writes through the same ref. A test whose only assertions are negative is the vacuous-pass shape; a positive sibling is the cheap proof the sink is live. Source identity and the immune cases → references/test-console.md; TestConsole.logLines accumulation → references/false-greens.md.

A test that cannot fail is worse than no test — mutate the edges

A green suite proves nothing about the properties no test can observe. The discipline: capture a baseline (git status --porcelain > /tmp/baseline), break the implementation in the way the property forbids (with the editor — never git checkout/git stash, other work lives in the tree), watch that exact test go red, revert, and confirm the status matches the baseline.

  • The assertion must DISCRIMINATE — fail for the right reason.
  • The failure to look for is a rule with no input that could falsify it. Ask of every rule: what input would make this fire alone, and does it exist? Mutate per clause and per path; two code paths implementing one rule are two things to pin, not one.
  • as const satisfies ReadonlyArray<Union> enforces NOTHING about exhaustiveness — use a residue-must-be-empty type or a total Record<Union, …>.
  • One assertion, one rule. A passing test is evidence about the path it takes, not about the rule it appears to test.
  • Before acting on "nothing found", run a control that FIRES, with a non-zero expected answer, against a KNOWN-GOOD input.
  • Read the failure TEXT; never infer a catch from a missing pass line. Empty output is a failed experiment.
  • Never verify a change by grepping for the text you just wrote. Only a mutation finds the emit site.
  • A semantics-preserving perf fix cannot be pinned — report it as fixed-but-unpinned.
  • A surviving mutant is a question about the CODE; deleting the code is a legitimate answer. When sweeping, assert the on-disk state every run, and settle disagreeing reads against git show HEAD:<path>.

Full discipline, the checklist, the satisfies spellings that do fire and the worked failures → references/mutation-testing.md.

Structural checks over source text

An invariant a type cannot express — "this module does not reach that dependency", "the entrypoint exports this by name" — gets pinned by asserting over source text, and those assertions fail silently where ordinary ones shout. Raw source is SAFE for a notInclude check (a comment mention is a spurious alarm) and DANGEROUS for an include one (a comment mention passes). Strip comments — LINE comments before block comments — remove module specifiers, match on a word boundary, and give the stripper its own discriminating test once it is load-bearing → references/structural-checks.md.

Other false greens, in one place

Tests: 0/0 passed is a FAILED run whose summary line says passed (a filter that matched no test file; the separate ERR_LOAD_URL a repo suffers while its config declares a cwd-relative globalSetup path is a config defect to fix, not a cwd rule to obey); TestConsole.logLines accumulation; the eager layerNoop recorder; PubSub.takeAll hanging on an empty subscription; a drain test whose subscriber took every message inside publish, so nothing was ever queued; PubSub.shutdown dropping the tail it was meant to drain; a stream over an ended subscription repeating PubSub.end's sticky final message forever; a race that only shows below the default Scheduler.MaxOpsBeforeYield budget; timing gates lying under coverage, and a timing guard that cannot catch a loop that never returns (its control runs in a subprocess with a hard timeout); a green suite that fails the vitest process because a test left process.exitCode set; a big green count for a surface the suite never calls; a helper used on both sides of every comparison, which agrees with itself however broken it is; an Effect.timeout guard that never fires — under it.effect any guard is inert until TestClock.adjust passes it, and under a real clock a guard of 5 seconds or more loses to vitest's own default; a forked fiber's failure that is never observed anywhere unless the fiber is joined. Each with its probe → references/false-greens.md.

Zero collected tests is never a pass — read BOTH the Tests line and the exit code. A filter that matches no test file prints Tests: 0/0 passed and exits 1: the Tests line is the liar and the exit code is honest. Treat any disagreement between the two signals as the alarm, and read unhandledErrors alongside both. Run vitest from the repo root — from inside a package it does not load the root config — and never --passWithNoTests. In a kit monorepo a workspace link resolves to a sibling's src/, so no sibling needs building first; only a test that reads its own dist does, and a globalSetup build through AgentPlugin.runScript is not a guarantee against it: the script is skipped while its done-marker is younger than VITEST_AGENT_RUNSCRIPT_BUILT_RECENTLY_MS (30 s by default), so pin that to 1 in the setup or a run inside the window reads the previous build. The ERR_LOAD_URL setup-file case and the rest → references/running-the-suite.md.

Test the sync facade over the same fixture as the Effect form

When an external consumer calls a synchronous facade (a *Sync function, or a parseResult/Result form beside an Effect one), the facade is a separate code path and a green Effect-form suite proves nothing about it. Run the facade over the same fixture the Effect form reads and assert the same answer. The facade can fail where the service passes: a layout only the Effect suite had a fixture for (a yarn repository's package.json#workspaces, say) discovers members through the service while the sync facade the consuming tool calls returns none.

Piping vitest into tail (or head, grep) hides its exit code. The pipe reports the last command's status, so a failing run looks green. Under zsh or bash use set -o pipefail before the pipeline (or read ${PIPESTATUS[0]} / $pipestatus[1]), or redirect to a file and read the code of the vitest command itself.

House conventions

  • Tests live in each package's __test__/ directory (*.test.ts), never co-located in src/.
  • A probe writes no file. A probe left under __test__/ is collected by the ordinary suite and inflates the Tests: count. Run it as a script that never touches disk, from inside the package: cd packages/<name> && node --input-type=module -e '<script>' → references/running-the-suite.md.
  • Construct domain values via the schema's X.make, never new.
  • In this monorepo, assert with assert.* from @effect/vitest, never expect — the root CLAUDE.md mandates it and every test file here obeys. toEqual → assert.deepStrictEqual; toBe → assert.strictEqual; toBeInstanceOf → assert.instanceOf; toBe(true) → assert.isTrue; toHaveLength → assert.lengthOf. This is house convention, not a technical constraint — expect works unchanged inside it.effect, so in a repo whose house style is expect, do not sweep it. Follow the host repo.
  • Keep the boundary honest: assert that the package's own error escapes (error._tag === "JsoncParseError"), and that the schema path surfaces a SchemaError — the two must not drift.
  • A test that cannot fail is worse than no test. Two cases beyond the walker eight: a prototype-pollution guard whose payload could never mutate the asserted object, and a @ts-expect-error in a tsconfig-excluded file.

04 同仓库更多 Skills

spencerbeggs
spencerbeggs/effected

testing-actions

Use when writing or reviewing tests for @effected/github-actions, @effected/github, @effected/sbom or @effected/commands — stubbing the GitHub API, writing a service's layerTest or makeTest double, testing the pre/main/post lifecycle through Action.run, or debugging why a test hits the real network or hangs.

★ 8
spencerbeggs
spencerbeggs/effected

supply-chain-attestation

Use when generating a CycloneDX SBOM, checking NTIA minimum elements, building an in-toto statement or a SLSA provenance predicate, signing into a Sigstore DSSE bundle, or uploading an attestation to GitHub.

★ 8
spencerbeggs
spencerbeggs/effected

structuring-an-action

Use when laying out a new GitHub Action repository on the @effected suite, deciding where a piece of code belongs (an entry point, a step, a shared service, a shim), or reviewing an existing action's file structure against the canonical shape.

★ 8
spencerbeggs
spencerbeggs/effected

running-commands-and-tools

Use when running a subprocess in Effect v4, spawning a command, capturing stdout/stderr/exit code, checking whether a CLI tool is installed or which copy to run, running a package-manager script through the project's launcher, detaching a background process, or redacting a secret from argv or captured output.

★ 8
spencerbeggs
spencerbeggs/effected

release-and-publish

Use when publishing a package to npm, reading the npm registry from Effect v4, checking whether a version is already published, cutting a release tag or GitHub release from an action, applying a release-age gate, or deriving tracking tags for GitHub Actions distribution.

★ 8
spencerbeggs
spencerbeggs/effected

hardening-a-parser-port

Use when porting or writing a recursive-descent parser, lexer, or tree-walker over untrusted text in the @effected monorepo — the class of hardening the cloud reviewer scans for on every migration. Covers stack-overflow depth guards (on EVERY recursion surface, which a facade has N of — not two), numeric bound guards that must reject NaN and non-integers, code-point range checks scoped to formats with wide escapes, prototype-pollution, control-character rejection, and the invariant that malformed input must fail through the typed error channel, never as an unhandled defect.

★ 8