/walkeros-testing-strategy

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:**

jest.mock('../ga4', () => ({ initGA4: jest.fn() }));
expect(initGA4).toHaveBeenCalledWith(...);

**Right:**

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.

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:

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 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:**

class Session {
  destroy() {
    /* only used in tests */
  }
}

**Right:**

// 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:**

# 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:**

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 = rec