walkeros-testing-strategy

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);
      }
    },
  );
});