Effect v4 CLI testing
The CLI test suite (ts/packages/cli/test/) runs on effect@^4.1.0 and
@effect/vitest@^4.1.0 (matching range, matching ts/packages/cli/package.json and the
workspace catalog in pnpm-workspace.yaml). @effect/cli and @effect/platform no longer exist
as dependencies — their functionality moved into effect/effect/*. Read
ts/packages/cli/test/__utils__/services/test-layer.ts before writing a new test suite; it is the
canonical example of every pattern below. For source-side v4 conventions (service definitions,
typed errors, the effect/cli command surface) rather than test-specific ones, use the
repo-local effect-v4 skill.
Runner APIs
it.effectis the default tester. It runs insideEffect.scopedautomatically, so a v3-styleit.scopedis unnecessary — v4's@effect/vitestno longer exportsit.scoped.it.liveruns against the real (non-TestClock) environment. Reach for it only when the code under test sleeps outside Effect's clock; a retry, timeout, orEffect.sleepinside the code under test is driven onit.effectby forking the effect, loopingEffect.yieldNowandTestClock.adjustuntilfiber.pollUnsafe()is set, andFiber.join(see "Time in tests" in theeffect-v4skill's core-patterns reference). The exception is a test that answers the API client itself with a retryable response. It answers withretry-after-ms: 0and runs on the live clock, as that section describes.- Reusable service layers go through
layer(...), not manualEffect.providescattered per test:
import { describe, expect, layer } from '@effect/vitest';
import { ConfigProvider, Effect } from 'effect';
import { cli, pkg, TestLive, MockConsole } from 'test/__utils__';
describe('CLI: composio', () => {
layer(TestLive())(it => {
it.effect("[Given] no arguments [Then] prints composio's version from package.json", () =>
Effect.gen(function* () {
yield* cli(['version']);
const lines = yield* MockConsole.getLines();
expect(lines.join('\n')).toContain(pkg.version);
})
);
});
const testConfigProvider = ConfigProvider.fromEnvRecord({ DEBUG_OVERRIDE_VERSION: '1.2.3-test' });
layer(TestLive({ baseConfigProvider: testConfigProvider }))('with config override', it => {
it.effect('[Given] `DEBUG_OVERRIDE_VERSION` env var [Then] prints overridden version', () =>
Effect.gen(function* () {
yield* cli(['version']);
const lines = yield* MockConsole.getLines();
expect(lines.join('\n')).toContain('1.2.3-test');
})
);
});
});TestLive (exported as TestLayer from test/__utils__/services/test-layer.ts, re-exported as
TestLive from test/__utils__/index.ts) takes an optional TestLiveInput — fixture,
toolkitsData, authConfigsData, connectedAccountsData, triggersData, realtimeData,
cliUserConfig, stdin, toolsExecutor, toolRouter, commandRunner, setupSkillInstaller,
terminalUI, baseConfigProvider — and builds the full service graph a CLI invocation needs, with
network calls mocked out. Smaller, module-local suites that only touch one or two services build a
narrower Layer.mergeAll(...) inline instead of pulling in the full TestLive (see
test/src/effects/decode-connected-account-list.test.ts), and unit-level suites that only need a
single service override can pass a bare Layer.succeed(Service, {...}) straight into
Effect.provide (see test/src/effects/detect-platform.test.ts).
Explicit test layers, not .Default
v4's Context.Service classes have no auto-generated .Default layer the way v3's
Effect.Service classes did. Every service in src/services/ now exports an explicit static layer
(NodeOs.Default, JsPackageManagerDetector.Default, ProjectEnvironmentDetector.Default,
ProjectContext.Default; a smaller set uses .layer instead — UpgradeBinary.layer,
TriggersRealtime.layer) built with Layer.effect(this, this.make) or an equivalent
Layer.succeed/Layer.effect composition. Match whichever static the service under test actually
exports — check the service file itself; do not assume .Default universally.
For mocks, construct the service shape with Service.of({...}) (not new Service({...}) — v4
Context.Service class constructors are type-metadata-only and no longer double as a runtime shape
constructor) and wrap it with Layer.succeed(Service, Service.of({...})).
The @effect/platform-bun subpath rule
Never import the @effect/platform-bun package barrel (import { BunContext } from '@effect/platform-bun') from src/ or test/. The barrel re-exports BunRedis, which requires
the native bun package at module-load time and crashes the Node-hosted Vitest runner immediately
on import, before any test in the file can run — even if the file never touches Redis. Always
import the specific subpath instead:
import * as BunFileSystem from '@effect/platform-bun/BunFileSystem';
import * as BunPath from '@effect/platform-bun/BunPath';
import * as BunServices from '@effect/platform-bun/BunServices';BunServices.layer is the v4 replacement for v3's BunContext.layer — it bundles
FileSystem/Path/Terminal/Stdio/ChildProcessSpawner/Crypto in one layer. Reach for the narrower
BunFileSystem.layer / BunPath.layer when a suite only needs filesystem/path, to keep the
provided service set legible. test-layer.ts composes exactly this set of subpath imports; treat
any new @effect/platform-bun import elsewhere in the CLI package as a rule violation, not a style
choice.
Other v4 test-surface renames worth knowing
Either→Result:Effect.either→Effect.result,Either.isLeft→Result.isFailure,.left/.right→.failure/.success.ParseResult.ParseError→Schema.SchemaError; assert withSchema.isSchemaError(error).Effect.catchAll→Effect.catch;Effect.fork→Effect.forkChild(bare fork) /Effect.forkDetach(daemon-style, wasEffect.forkDaemon).Console.ConsoleandConfigProvider.ConfigProviderareContext.References, not FiberRef- or Layer-hidden state — provide them withLayer.succeed/Layer.effectand preferLayer.provideMergeoverLayer.providewhen the reference's value must stay visible to everything downstream (see theConfigProvidercomment intest-layer.tsfor the bug this distinction fixed).TestClocklives undereffect/testing;TestClock.adjust('1 minute')resumes every sleep scheduled inside the window, including ones a resumed retry schedules next. The FastCheck bridge was removed in rc.113; native arbitrary generation lives undereffect/Arbitrary.
CLI behavior matrix
Port tests by contract, not file count:
- root and subcommand help, version, built-ins, aliases, and flag collisions;
- required, optional, repeated, invalid, and dash-leading arguments, including
--; - stdout data versus stderr decoration in interactive and piped modes;
- CLI framework errors (
effect/cli'sCliError) versus Composio domain error (Data.TaggedError) rendering and exit-code mapping; - shared service layers, config providers, filesystem/process adapters, interruption, time, and cleanup;
- direct binary smoke tests and Docker CLI E2E after unit and package checks pass.
Authoring-skill examples
bun run validate:cli-skills compiles the skill snippets, checks linked excerpts against current source, and runs the documented teaching command through cliExit() over TestLive. Its request assertions use the native @composio/client/effect implementation over the recording HTTP transport from test/__utils__/services/stub-composio-client.ts. The same command also runs the existing registration and invocation contracts and Effect diagnostics.
This is recipe and contract verification. It does not measure agent performance on an unseen authoring task. The separate trial protocol lives in the cli-command command-example reference.