UNPKG

@augmentcode/ag-redux-toolkit

Version:

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.

227 lines (186 loc) • 10.2 kB
--- name: core/testing description: >- Required vi.mock("typed-redux-saga") boilerplate mapping each effect to redux-saga/effects so redux-saga-test-plan can interpret them (the call mock MUST use Array.isArray to handle [context, method] tuple calls). Use expectSaga for integration (.withState / .put / .call / .provide / .dispatch / .silentRun) and testSaga for step-by-step (.next / .fork / .isDone). Reducer tests are pure — assert reference equality on no-op actions. State-integrity verification must prove derived values live in selectors and action/selector/saga owners are not duplicated. Source: docs/TESTING.md, ../SKILL.md §14. type: sub-skill library: ag-redux-toolkit requires: - core - core/sagas - core/state-integrity sources: - augmentcode/ag-redux-toolkit:docs/TESTING.md - ../SKILL.md triggers: - vi mock typed-redux-saga - expectSaga integration - testSaga stepwise - saga test plan --- # 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 | Layer | Test style | Required cues | | --- | --- | --- | | Reducers | Direct function calls | Initial state, each handled action, unknown/no-op same reference, serializable state when shape changes. | | Collections | Reducer/selector tests | Assert via `getItem`, `getItems`, or selector helpers; include no-op reference checks. | | Selectors | Pure `.select(mockState, ...)` calls | Never invoke readable selector form in Vitest. Test composition separately and together. | | Sagas | `expectSaga` or `testSaga` | Mock `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 | Case | Example | | --- | --- | | 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 `put`s. | 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.