Skip to content

@augmentcode/ag-redux-toolkit

Redux + Saga state management for Svelte apps — designed for AI agents. Includes runtime TypeScript source, AI skills, and reference documentation for robust, observable, high-performance state management.

core/testing

sub-skill
227 linesSource

>-

Testing — reducer, selector, and saga checks

Operational testing checklist. Human-facing examples: docs/TESTING.md. Saga effect details: ../sagas/SKILL.md. Source: ../SKILL.md §14.

Use when

  • Adding or updating tests for reducers, selectors, collections, async actions, or sagas.
  • Reviewing state-integrity evidence for changed state/actions/selectors/sagas.
  • Debugging redux-saga-test-plan matcher failures.

Layer rules

LayerTest styleRequired cues
ReducersDirect function callsInitial state, each handled action, unknown/no-op same reference, serializable state when shape changes.
CollectionsReducer/selector testsAssert via getItem, getItems, or selector helpers; include no-op reference checks.
SelectorsPure .select(mockState, ...) callsNever invoke readable selector form in Vitest. Test composition separately and together.
SagasexpectSaga or testSagaMock typed-redux-saga, stub calls with redux-saga-test-plan/matchers, use silentRun.

Saga test setup cues

  • Mock only the typed-redux-saga effects the file uses and map them to redux-saga/effects before importing the saga under test.
  • The call mock must branch on Array.isArray(fnOrDescriptor) so [context, method] tuple calls work.
  • In assertions and matchers, use redux-saga/effects descriptors or redux-saga-test-plan APIs, not descriptors imported from typed-redux-saga.
  • Use expectSaga for behavior/integration and testSaga for order-sensitive generator steps such as root saga fork order.

State-integrity evidence

  • Reducer tests assert canonical fields only; derived values are tested through selectors.
  • Selector tests cover derived outputs instead of stored filtered*, *Count, has*, or selected entity copies.
  • Handoff names the canonical owner for each new action, selector, or saga, or states that none was added.
  • Search evidence lists terms/paths used to rule out duplicate action types, selectors, saga watchers, and registrations.

Don't

  • Do not call selector() in tests; use .select(state).
  • Do not use real long timers in saga tests; prefer .silentRun(0) or a short bounded duration.
  • Do not approve tests that assert reducer-maintained derived fields when selectors should own that value.
  • Do not omit no-op reference checks for reducers or collection updates that should preserve identity.
  • Do not leave one-line re-export/proxy wrapper files after refactors unless an adjacent compatibility comment documents the consumer, release window, and removal condition.

Example list

  1. Good: typed-redux-saga Vitest mock with the required tuple-aware call guard.
  2. Good: reducer tests for handled actions, async failure, and no-op reference equality.
  3. Good: selector tests that assert derived output through .select(state, ...args).
  4. Good: expectSaga integration test that provides selector effects and API calls.
  5. Good: testSaga stepwise root-saga watcher assertion.
  6. Bad: realistic tests that assert stored derived state, call readable selector mode, and miss selector-effect providers.

Cases covered

CaseExample
Saga test setup maps typed effects to redux-saga/effects and keeps [context, method] calls working.1
Reducer tests prove handled branches and same-reference no-op behavior.2
Selector tests cover derived values through public .select instead of reducer-owned derived fields.3
Saga integration tests provide selector.effect() and API effects before asserting puts.4
Stepwise saga tests are reserved for order-sensitive watcher/root-saga checks.5
Bad examples teach non-trivial review failures that compile but can produce misleading tests.6

Examples

1. Mock typed-redux-saga with a tuple-aware call guard

ts
import { vi } from "vitest";
import * as effects from "redux-saga/effects";

vi.mock("typed-redux-saga", () => ({
  call: (fnOrDescriptor: any, ...args: any[]) =>
    Array.isArray(fnOrDescriptor)
      ? effects.call(fnOrDescriptor, ...args)
      : effects.call(fnOrDescriptor, ...args),
  put: effects.put,
  select: effects.select,
  takeLatest: effects.takeLatest,
}));

2. Test reducer branches and no-op identity

ts
import { describe, expect, it } from "vitest";
import { createAction, createAsyncAction } from "@augmentcode/ag-redux-toolkit/utils/store/create-action";
import { createReducer } from "@augmentcode/ag-redux-toolkit/utils/store/create-reducer";

type TodosState = { items: string[]; filter: "all" | "open"; loading: boolean; error: string };
const setFilter = createAction<[filter: TodosState["filter"]]>("todos/setFilter");
const loadTodos = createAsyncAction<[query: string], { query: string }, string[]>("todos/loadAsync", "todos/load", (query) => ({ query }));
const initialState: TodosState = { items: [], filter: "all", loading: false, error: "" };
const todosReducer = createReducer(initialState)
  .with(setFilter, (state, { payload: [filter] }) => (state.filter === filter ? state : { ...state, filter }))
  .with(loadTodos, (state) => ({ ...state, loading: true, error: "" }))
  .with(loadTodos.failure, (state, { payload }) => ({ ...state, loading: false, error: payload.error.message }));

describe("todosReducer", () => {
  it("keeps no-op identity and covers async failure", () => {
    const current: TodosState = { ...initialState, filter: "open" };
    expect(todosReducer(current, setFilter("open"))).toBe(current);
    expect(todosReducer({ ...current, loading: true }, loadTodos.failure(new Error("Network"))).error).toBe("Network");
  });
});

3. Test selector output through .select(state)

ts
import { describe, expect, it } from "vitest";
import { selectTodoCount, selectVisibleTodos } from "./todos-selectors";

const state = {
  todos: {
    items: [{ id: "a", title: "Write tests", completed: false }, { id: "b", title: "Review", completed: true }],
    filter: "open",
  },
};

describe("todo selectors", () => {
  it("derives visible todos from canonical reducer state", () => {
    expect(selectVisibleTodos.select(state).map((todo) => todo.id)).toEqual(["a"]);
    expect(selectTodoCount.select(state)).toBe(2);
  });
});

4. Use expectSaga with provided selector effects

ts
import { describe, it } from "vitest";
import { expectSaga } from "redux-saga-test-plan";
import * as matchers from "redux-saga-test-plan/matchers";
import { fetchTodos } from "./todos-api";
import { loadTodos, loadTodosWorker } from "./todos-saga";
import { selectCurrentUserId } from "./todos-selectors";

describe("loadTodosWorker", () => {
  it("loads todos for the selected user", () => {
    const todos = [{ id: "t1", title: "Ship examples", completed: false }];
    return expectSaga(loadTodosWorker, loadTodos("open"))
      .provide([[selectCurrentUserId.effect(), "u1"], [matchers.call.fn(fetchTodos), todos]])
      .put(loadTodos.success(todos))
      .silentRun();
  });
});

5. Use testSaga for root watcher order

ts
import { describe, it } from "vitest";
import { testSaga } from "redux-saga-test-plan";
import { loadTodos, loadTodosWorker, todosRootSaga } from "./todos-saga";

describe("todosRootSaga", () => {
  it("registers the canonical latest-only watcher", () => {
    testSaga(todosRootSaga)
      .next()
      .takeLatest(loadTodos, loadTodosWorker)
      .next()
      .isDone();
  });
});

6. ❌ Bad: misleading selector and saga assertions

ts
import { expect, it } from "vitest";
import { expectSaga } from "redux-saga-test-plan";
import * as matchers from "redux-saga-test-plan/matchers";

// BAD: this test passes syntax checks but validates duplicated derived state, invokes readable mode,
// and forgets to provide the selector effect that the worker reads before calling the API.
it("claims the todo flow works", () => {
  const nextState = todosReducer(state, setFilter("open"));
  expect(nextState.visibleTodos).toEqual([todo]);
  expect(selectVisibleTodos()).toEqual([todo]);

  return expectSaga(loadTodosWorker, loadTodos("open"))
    .provide([[matchers.call.fn(fetchTodos), []]])
    .put(loadTodos.success([]))
    .silentRun();
});

Verification cues

  • Run the smallest relevant test scope first, then broader validation if needed.
  • Run architecture validation for state/actions/selectors/sagas changes when in scope: npm run validate:architecture in this repository, or run ESLint with the app's composed domain root config imported from @augmentcode/ag-redux-toolkit/eslint-plugins in a consuming app.
  • Review docs/skills examples after changing them and run the smallest relevant test scope first.
  • Manual review should confirm detailed background stays in docs/TESTING.md while this skill keeps only concise, gate-focused examples.

See also

  • docs/TESTING.md — human reference with reducer, selector, saga, and integration examples.
  • core/reducers/SKILL.md — reducer purity and reference equality.
  • svelte/selectors/SKILL.md — .select(state) selector testing.
  • core/sagas/SKILL.md — saga effect and watcher conventions.
  • core/state-integrity/SKILL.md — canonical ownership evidence.