walkeros-testing-strategy
/walkeros-testing-strategy
Prowadzi pisanie i przegląd testów pakietów walkerOS, obejmując wzorzec env, przykłady deweloperskie i strategie dla poszczególnych pakietów.
- Autor
- elbwalker ↗
- Repozytorium
- walkerOS ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 22.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 1
Brak sygnałów. Repozytorium zmienione 22.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Prowadzi pisanie i przegląd testów pakietów walkerOS, obejmując wzorzec env, przykłady deweloperskie i strategie dla poszczególnych pakietów.
Oryginalny opis (EN)
Use when writing tests, reviewing test code, or discussing testing approach for walkerOS packages. Covers env pattern, dev examples, and package-specific strategies.
Jak działa
- Overview
- The Rules
- When to Use Each Test Type
- Simulation Testing
- Package-Specific Approaches
- The env Pattern Deep Dive
- Red Flags - Stop and Fix
- Commands
- Reading a Step Back from the Collector
- Destination Test Duplication, Pending Cleanup
Podgląd SKILL.md
---
name: walkeros-testing-strategy
description:
Use when writing tests, reviewing test code, or discussing testing approach
for walkerOS packages. Covers env pattern, dev examples, and package-specific
strategies.
---
# walkerOS Testing Strategy
## Overview
walkerOS uses a layered testing approach with built-in patterns for mocking and
documentation sync. This skill ensures tests are reliable, efficient, and
maintainable.
**Core principle:** Test real behavior using the `env` pattern, link to `dev`
examples, verify before claiming complete.
## The Rules
### Rule 1: Use `env` for Mocking, Not Jest
walkerOS has a built-in dependency injection pattern via `env` in context. This
is lighter than Jest mocks, enables documentation generation, and keeps tests in
sync with examples.
**Wrong:**
```typescript
jest.mock('../ga4', () => ({ initGA4: jest.fn() }));
expect(initGA4).toHaveBeenCalledWith(...);
```
**Right:**
```typescript
import { examples } from '../dev';
import { mockEnv } from '@walkeros/core';
const calls: Array<{ path: string[]; args: unknown[] }> = [];
const testEnv = mockEnv(examples.env.push, (path, args) => {
calls.push({ path, args });
});
await destination.push(event, { ...context, env: testEnv });
expect(calls).toContainEqual({
path: ['window', 'gtag'],
args: ['event', 'page_view', { page_title: 'Home' }],
});
```
### Rule 2: Link Tests to `dev` Examples
The `dev.ts` export provides `examples.env`, `examples.events`,
`examples.mapping`, and `examples.step`. Using these in tests ensures
documentation stays in sync.
```typescript
import { examples } from '../dev';
// Use examples.env for mock environment
const testEnv = mockEnv(examples.env.push, interceptor);
// Assert against examples.events (documented expected output)
expect(calls[0].args).toEqual(examples.events.ga4PageView());
// Test with examples.mapping configurations
const config = { mapping: examples.mapping.ecommerce };
```
#### Step Examples with `it.each`
Step examples (`examples.step`) provide `{ in, out }` pairs for each step. Use
`it.each` to iterate over them:
```typescript
import { examples } from '../dev';
describe('step examples', () => {
it.each(Object.entries(examples.step))(
'%s',
async (name, { in: input, out: expected }) => {
const result = await step.push(input, context);
if (expected === false) {
expect(result).toBe(false);
} else {
expect(result).toEqual(expected);
}
},
);
});
```
See [using-step-examples](../walkeros-using-step-examples/SKILL.md) for the full
lifecycle including the Three Type Zones and naming conventions.
### Rule 3: Test Real Behavior, Not Mock Behavior
If you're asserting that a mock was called, you're testing the mock works, not
the code.
**Red flags:**
- `expect(mockFn).toHaveBeenCalled()` without verifying the mock produces real
effects
- Assertions on `*-mock` test IDs
- Tests that pass when mock is present, fail when removed
**Fix:** Test what the code actually does. If external APIs must be mocked,
verify the real API would receive correct data.
### Rule 3b: Prove Delivery, Loss and Failures on a Real Collector
A test or repro that claims an event was delivered, lost or reported as failed
starts a real collector with `startFlow` and mocks only the network or the
vendor global (through `env`), never `collector.push`. A suite that mocks the
collector cannot see loss: a destination that returns early, swallows an error
or forgets an `await` passes it. Assert on what a user sees at default settings:
the push result (`ok: false`, the destination under `failed` with its `reason`),
the status counters, or the ERROR line the collector wrote.
Failure paths are examples too. A step package's failure modes (a missing
required setting, a failing transport, a vendor script that is not loaded yet)
are `public: false` step examples with an `outcome` (and `respond` for a vendor
answer), not only the happy path. A `silent` rule and a consent revocation get
examples as well.
**Use the conformance kit.** `conformance(kind, step, options)` from
`@walkeros/collector/dev` runs a destination, source, transformer or store on a
real collector against its step examples and checks the failure contract in one
call. The `profile` states what the step talks to: for destinations `http`,
`sdk-env`, `web-sdk` (a web SDK started in `init`), `vendor-global` or `socket`;
`transformer` and `source` for those kinds. A web step passes `page` from
`@walkeros/web-core/dev`, the browser it runs on; the browser profiles fail
without it. `runExamples` runs the examples alone.
### Rule 4: Test First, Watch It Fail
If you didn't see the test fail, you don't know it tests the right thing.
**Process:**
1. Write failing test
2. Verify it fails for expected reason (missing feature, not typo)
3. Write minimal code to pass
4. Verify it passes
5. Refactor if needed
**Red flags:**
- Test passes immediately when written
- Can't explain why test failed
- "I'll add tests later"
### Rule 5: No Test-Only Methods in Production Code
Production classes shouldn't have methods only tests use.
**Wrong:**
```typescript
class Session {
destroy() {
/* only used in tests */
}
}
```
**Right:**
```typescript
// In test-utils/
export function cleanupSession(session: Session) { ... }
```
### Rule 6: Verify Before Claiming Complete
"Should pass now" is not verification.
**Process:**
1. Run the actual test command
2. Read the output
3. Confirm pass/fail count
4. Only then claim status
## When to Use Each Test Type
| Type | When to Add | Example |
| --------------- | ------------------------------------------------------------------- | -------------------------------------------------------------- |
| **Integration** | New usage pattern, new external API interaction, new data flow path | Collector → Destination → gtag() |
| **Unit** | Combinatorics, edge cases, pure function logic | Mapping variations, core utilities |
| **Contract** | Boundary validation | Destination output matches vendor API, source input validation |
**Guideline:** Integration tests prove things work when stuck together. Unit
tests efficiently cover variations. Contract tests catch API drift.
## Simulation Testing
Simulation testing uses the CLI `push` command with `--simulate` flags. The
collector does not export a `simulate()` function — simulation is a CLI concern
that maps to `mock`/`disabled` config properties at runtime.
**CLI usage:**
```bash
# Simulate a destination (mocks its push, captures API calls)
walkeros push flow.json -e '{"entity":"page","action":"view"}' --simulate destination.ga4
# Simulate a source (captures events it pushes, disables all destinations)
walkeros push flow.json --simulate source.browser
# Mock a destination with a specific return value
walkeros push flow.json -e event.json --mock destination.ga4='{"status":"ok"}'
```
**Programmatic usage:**
```typescript
import { simulateDestination, simulateSource } from '@walkeros/cli';
// Simulate a destination: returns one Simulation.Result
const dest = await simulateDestination(
'flow.json',
{ name: 'page view' },
{ destinationId: 'ga4', ingest: { userAgent: 'Mozilla/5.0' } },
);
// dest.calls = recorded vendor calls ({ fn, args, ts })
// dest.mappingKey = matched rule, e.g. "page view"
// Simulate a source: input is { content, trigger? }
const src = await simulateSource(
'flow.json',
{ content: { name: 'page view' } },
{ sourceId: 'browser' },
);
// src.events = events captured from source env.push
```
`simulateTransformer` and `simulateCollector` follow the same shape. The CLI
`push --simulate` path collects these results into `PushResult.simulations` and
prints them with `formatPushResult`; programmatic `push()` does not simulate.
**Key points:**
- `--simulate destination.X` starts only the target destination (no source, no
other destination); the flow's transformers still start
- `--simulate source.X` starts only that source and captures its events at the
collector boundary; they reach no destination. A source package declaring
`examples.env.simulation` (SQS, Pub/Sub pull) runs on its mock client, calls
recorded
- Simulate options: `--consent` (starting collector consent), `--command`
(destination runs a collector command instead of a push), `--page-url` (web
source page), `--ingest` (request context). Programmatic:
`simulateDestination(config, event, { destinationId, consent, command })`,
`simulateSource(config, input, { sourceId, pageUrl })`
- Destination `/dev` env.push is auto-loaded to provide mock globals (fake
`window.gtag`, a mock SDK client, a mock `sendServer`), resolved per export
(`exportExamples`). Without one, simulate refuses a package destination before
the flow starts instead of calling the real vendor (an inline `code` step has
no package and runs as given). A flow store's mock env is injected when its
package ships one; a store without one runs for real.
- Returns `PushResult` with `simulations` (one `Simulation.Result` per simulated
step: `events`, `calls`, `mappingKey?`, `skipped?`, `error?`; `skipped` says
why a destination sent nothing: `pending` on its `require`, or a `consent`
skip)
- Trace-mode limit: simulate injects the mock env before `init`, so a client
built in `init` is recorded. Runtime trace mode wraps the env per push only
(`collector/src/destination.ts`), so calls through a client built in `init`
are not recorded there.
- The `mockEnv()` and env pattern examples above remain correct for unit testing
individual step functions directly
## Package-Specific Approaches
| Package | Approach |
| ----------------------- | ------------------------------------------------------------------------------- |
| **core** | Unit tests only - pure functions, no env needed |
| **collector** | Integration tests critical - input/output consistency is paramount |
| **browser source** | Maintain walker algorithm coverage |
| **web destinations** | Integration tests per unique pattern + unit tests for mappings, use env pattern |
| **server destinations** | Same as web destinations |
| **cli/docker** | Integration tests for spawn behavior, explore dev pattern to reduce duplication |
| **sources** | Contract tests for input validation, integration tests for event capture |
## The env Pattern Deep Dive
### How env Works
Each destination/source defines an `env` type that specifies external
dependencies:
```typescript
// Destination-specific env type
export interface Env extends DestinationWeb.Env {
window: {
gtag: Gtag.Gtag;
dataLayer: unknown[];
};
document: {
createElement: (tagName: string) => HTMLElement;
head: { appendChild: (node: unknown) => void };
};
}
```
### mockEnv() Function
The `mockEnv()` function from `@walkeros/core` creates a Proxy that intercepts
all function calls:
```typescript
import { mockEnv } from '@walkeros/core';
const calls: Array<{ path: string[]; args: unknown[] }> = [];
const testEnv = mockEnv(examples.env.push, (path, args) => {
calls.push({ path, args });
// Optionally return a value
});
// Now use testEnv in your destination context
await destination.push(event, { ...context, env: testEnv });
// Assert on captured calls
expect(calls).toContainEqual({
path: ['window', 'gtag'],
args: ['event', 'purchase', expect.objectContaining({ value: 99.99 })],
});
```
### Rules for a package's env
- **`init` keeps an injected dependency.** Every external dependency (SDK
client, constructor or module, `fetch`, `sendServer`, auth client) is reached
through `env`, and `init` creates one only when none is injected:
`env?.x ?? (await createX(...))`. Overwriting an injected client means tests
and simulate hit the real vendor.
- **Every mock env key is read.** Each key a package's `examples.env.push`
declares must be read as `env.<key>` somewhere in the package's `src`;
otherwise the mock is dead and the real module runs (jest may pass only
through `__mocks__`).
- **`simulation` names the request call** and is pinned with
`expectSimulationResolves(examples.env)` from `@walkeros/core/dev` (see
[using-step-examples](../walkeros-using-step-examples/SKILL.md)).
### dev.ts Structure
Each package with external dependencies should have:
```typescript
// src/dev.ts
export * as schemas from './schemas';
export * as examples from './examples';
// src/examples/index.ts
export * as env from './env';
export * as events from './events';
export * as mapping from './mapping';
export * as step from './step'; // Step examples { in, out }
```
### Testing Sources with Injected env
Sources accept platform dependencies via `env`. Mock `window`, `document`, or
library imports by passing them through `env` instead of mocking globals.
Type the mock against the source's own `Env` type, not against the global
`Window`. A source narrows `Env.window` to only the members it touches, so the
mock satisfies that narrowed shape directly with **no `as unknown as Window`
cast**:
```typescript
import type { Env } from '../types'; // the source's narrowed Env
// Instead of mocking window.performance globally:
const env: Env = {
window: {
performance: {
getEntriesByType: jest.fn().mockReturnValue([{ type: 'navigate' }]),
},
location: { href: 'https://test.com/' },
},
};
await createSessionSource(collector, undefined, env);
// Instead of mocking express import, type the binding against the source's
// injected dependency type so the mock is assignable without a cast:
import type { SourceEnv } from './types';
const express: SourceEnv['express'] = Object.assign(
jest.fn().mockReturnValue(mockApp),
{ json: jest.fn().mockReturnValue(middleware) },
);
await sourceExpress(createSourceContext({}, { express }));
```
This pattern avoids global state pollution between tests, enables simulation in
non-browser environments, and stays cast-free because the source narrows its own
`Env` to exactly the members it uses (the same declare-global + narrowed-`Env`
approach destinations use — see
[create-destination §3.3.1](../walkeros-create-destination/SKILL.md)).
## Red Flags - Stop and Fix
- Using `jest.mock()` for internal modules when `env` pattern is available
- Tests that don't import from `../dev`
- Assertions only checking mock call counts
- Proving delivery or loss with a mocked `collector.push` instead of `startFlow`
- A destination without a conformance test, a `silent` example or a failure
example
- Tests with extensive mock setup (>50% of test is setup)
- Test-only methods added to production classes
- Claiming tests pass without running them
## Commands
Verification tier (per `/workspaces/developer/AGENT.md` rule 11):
```bash
# L1, the default during a task: typecheck, lint, test for the touched package
cd /workspaces/developer/walkerOS
npm run verify:touched -- core
npm run verify:touched -- web-destination-gtag
# L2, at plan completion: only packages affected since origin/main
git fetch origin main --depth=1
npm run verify:affected
# L3, before pushing or marking PR-ready: critical path + affected
npm run test:smoke
# Single test file (still useful while iterating)
cd packages/<name> && npm run test -- path/to/file.test.ts
# Watch mode (single package)
cd packages/<name> && npm run test -- --watch
```
Avoid bare `npm run test` at root inside per-task steps. That is L4 (full suite,
10-15 min) and is reserved for plan completion when the plan touched shared
infra, or for explicit user request.
## Reading a Step Back from the Collector
When a test calls a step's raw push directly through the collector bag
(`collector.sources.X.push`, `collector.destinations.X.push`, etc.), use the
typed accessors from `@walkeros/core` instead of casting:
```ts
import { Source } from '@walkeros/core';
const src = Source.getSource<TestSourceTypes>(collector, 'testSource');
await src.push({ method: 'GET', path: '/api/data' });
```
Available helpers: `Source.getSource`, `Destination.getDestination`,
`Transformer.getTransformer`, `Store.getStore`. Each accepts an optional type
parameter to recover the per-step generic that the bag's index signature erases
on read. Each throws `<Kind> not found: <id>` when the id is unknown.
Do not write `collector.sources.X.push as any` or
`collector.sources.X.push as (rawData: ...) => Promise<...>`. The accessor
exists exactly to remove that boundary cast.
## Destination Test Duplication, Pending Cleanup
As of 2026-04-29, web and server destination tests share substantial scaffolding
(init validation, missing-settings rejection, mock setup, push assertions) with
no shared harness. Audit found roughly 1500-2500 lines of repetition across 47
destinations. A typed shared harness is planned as a follow-on initiative.
When writing a new destination test today:
- Keep destination-specific behavior (mapping rules, vendor-specific batch
shapes, edge cases) in the test file.
- The boilerplate sections (env clone, `jest.clearAllMocks`,
missing-required-settings, init returns valid contract) are candidates for
extraction. Mirror the shape used by an existing destination of the same
family (web vs server) so the future migration is mechanical.
- Do NOT invent a new private harness inside the destination. If the missing
harness blocks you, flag it.
## Related Skills
- [walkeros-understanding-development](../walkeros-understanding-development/SKILL.md) -
Development conventions and workflow
**Reference:**
- [AGENT.md](../../AGENT.md) - Development guide
Wersje
W bazie nie ma innych skilli o nazwie walkeros-testing-strategy.
Migawka bazy z 13.11.2026 · wersja paczki e029d0adb139 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 95walkeros-using-step-examples
Prowadzi przez cały cykl pracy z przykładami kroków walkerOS: pisanie, symulację, walidację i testy, aż po integrację z CI. - 100walkeros-understanding-development
Wyjaśnia konwencje wkładu w walkerOS: przepływ build, test i lint, zasady XP, strukturę katalogów i korzystanie z pakietów, przed pisaniem kodu. - 100testing-strategy
Opisuje strategie testowania testów jednostkowych, integracyjnych i end-to-end: piramida testów, strategie mockowania i wytyczne dotyczące pokrycia. - 100testing
Opisuje zasady TDD i BDD przy pisaniu testów, przeglądzie pokrycia i ustalaniu strategii oraz architektury testów. - 100testing
Opisuje wytyczne testowania pakietów HoloViz: pisanie testów, przegląd pokrycia w PR i brakujące przypadki brzegowe. - 100testing-strategy
Planuje podział testów na jednostkowe, integracyjne i end-to-end, dobiera mocki i określa cele pokrycia kodu.