@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.
273 lines (208 loc) • 9.22 kB
Markdown
# Testing Guide
> **How to test reducers, selectors, and sagas.**
---
## Table of Contents
1. [Overview](#overview)
2. [Testing Reducers](#testing-reducers)
3. [Testing Selectors](#testing-selectors)
4. [Testing Sagas](#testing-sagas)
5. [Mock Store Setup](#mock-store-setup)
6. [Tips and Patterns](#tips-and-patterns)
---
## Overview
The testing approach for each layer follows from its design:
| Layer | Nature | Testing Approach |
|-------|--------|-----------------|
| Reducers | Pure functions | Call directly with state + action, assert result |
| Selectors | Pure functions | Call `.select(state)` with mock state, assert result |
| Sagas | Generators with effects | Use `redux-saga-test-plan` or step through manually |
Use [Vitest](https://vitest.dev/) as the test runner.
---
## Testing Reducers
Reducers are pure functions: given (state, action) → new state. Test them directly.
### Basic Pattern
```typescript
import { describe, it, expect } from "vitest";
import { counterReducer, increment, decrement, setCount } from "./counter-slice";
describe("counterReducer", () => {
const initialState = { value: 0, lastUpdated: null };
it("should return initial state for undefined state", () => {
const state = counterReducer(undefined, { type: "@@INIT" });
expect(state).toEqual(initialState);
});
it("should handle increment", () => {
const state = counterReducer(initialState, increment());
expect(state.value).toBe(1);
});
it("should handle setCount with payload", () => {
const state = counterReducer(initialState, setCount(42));
expect(state.value).toBe(42);
});
it("should return same state for unknown action", () => {
const state = counterReducer(initialState, { type: "unknown" });
expect(state).toBe(initialState); // Same reference
});
});
```
### Testing Async Action Handlers
```typescript
import { itemsReducer, fetchItems } from "./items-slice";
describe("itemsReducer async actions", () => {
const initialState = { items: [], isLoading: false, error: null };
it("should set loading on fetch request", () => {
const state = itemsReducer(initialState, fetchItems("query"));
expect(state.isLoading).toBe(true);
expect(state.error).toBeNull();
});
it("should store items on success", () => {
const items = [{ id: "1", name: "Item 1" }];
const state = itemsReducer(
{ ...initialState, isLoading: true },
fetchItems.success({ response: { items, total: 1 } })
);
expect(state.isLoading).toBe(false);
expect(state.items).toEqual(items);
});
it("should store error on failure", () => {
const state = itemsReducer(
{ ...initialState, isLoading: true },
fetchItems.failure({ error: new Error("Network error") })
);
expect(state.isLoading).toBe(false);
expect(state.error).toBe("Network error");
});
});
```
### Testing Collection Operations
```typescript
import { todosReducer, addTodo, removeTodo } from "./todos-slice";
import { getItem, getItems } from "@augmentcode/ag-redux-toolkit/utils/collections/collection-utils";
describe("todosReducer collections", () => {
it("should add a todo to the collection", () => {
const state = todosReducer(undefined, addTodo({ id: "1", title: "Test", completed: false }));
expect(getItem(state.collection, "1")).toEqual({
id: "1", title: "Test", completed: false,
});
});
it("should remove a todo from the collection", () => {
let state = todosReducer(undefined, addTodo({ id: "1", title: "Test", completed: false }));
state = todosReducer(state, removeTodo("1"));
expect(getItems(state.collection)).toHaveLength(0);
});
});
```
---
## Testing Selectors
Selectors are pure functions. Call `.select(state)` with a mock state object.
```typescript
import { describe, it, expect } from "vitest";
import { selectCompletedTodos, selectTodoById } from "./todos-selectors";
import { createCollection } from "@augmentcode/ag-redux-toolkit/utils/collections/collection-utils";
describe("selectCompletedTodos", () => {
const mockState = {
todos: {
collection: createCollection("id", [
{ id: "1", title: "Done", completed: true },
{ id: "2", title: "Pending", completed: false },
]),
},
};
it("should return only completed todos", () => {
const result = selectCompletedTodos.select(mockState);
expect(result).toHaveLength(1);
expect(result[0].id).toBe("1");
});
});
### Manual Generator Stepping
For more control, step through the generator manually:
```typescript
import { describe, it, expect } from "vitest";
import { call, put } from "typed-redux-saga";
import { handleFetch } from "./my-saga";
import * as api from "../api";
describe("handleFetch (manual)", () => {
it("should call API and dispatch success", () => {
const action = fetchItems("query");
const gen = handleFetch(action);
// Step 1: call the API
expect(gen.next().value).toEqual(call(api.fetchItems, "query"));
// Step 2: dispatch success with the result
const items = [{ id: "1" }];
expect(gen.next(items).value).toEqual(put(setItems(items)));
// Step 3: done
expect(gen.next().done).toBe(true);
});
it("should dispatch failure on error", () => {
const action = fetchItems("query");
const gen = handleFetch(action);
gen.next(); // Advance to call
const error = new Error("Network error");
expect(gen.throw(error).value).toEqual(put(fetchFailed(error.message)));
});
});
```
---
## Mock Store Setup
For integration-style tests that need a real store:
```typescript
import { describe, it, expect } from "vitest";
import { Store } from "@augmentcode/ag-redux-toolkit/svelte-store";
function createTestStore(overrides = {}) {
const store = new Store({
todos: todosReducer,
...overrides,
});
store.init();
return store;
}
describe("integration test", () => {
it("should handle full action flow", () => {
const store = createTestStore();
store.dispatch(addTodo({ id: "1", title: "Test", completed: false }));
const state = store.state;
expect(selectTodoById.select(state, "1")?.title).toBe("Test");
});
});
```
Use `Store` from `@augmentcode/ag-redux-toolkit/svelte-store` when a test needs Svelte-readable selector behavior. Use `StreamingStore` from `@augmentcode/ag-redux-toolkit/streaming-store` when asserting Kefir stream emissions from `store.createSelector(...)` calls; continue to use `.select(mockState, ...args)` for pure selector assertions. For direct streaming emission tests, use controlled timers or a mocked `requestAnimationFrame` to advance the selector throttle and assert that rapid Store or observable argument updates coalesce to the latest value.
---
## Tips and Patterns
1. **Test reducers exhaustively** — They are pure and fast. Cover every action type, edge cases, and identity returns.
2. **Test selector composition** — If `selectB` depends on `selectA`, test both independently AND together.
3. **Use `.select()` in tests** — Never call `selector()` (the readable form) in tests, as it requires Svelte component context.
4. **Assert immutability** — Verify that the original state is never mutated:
```typescript
it("should not mutate original state", () => {
const original = { ...initialState };
const frozen = Object.freeze(original);
// Should not throw
const newState = myReducer(frozen, myAction());
expect(newState).not.toBe(frozen);
});
```
5. **Test serialization** — Ensure state is always JSON-serializable:
```typescript
it("should produce serializable state", () => {
const state = myReducer(undefined, myAction());
expect(() => JSON.stringify(state)).not.toThrow();
expect(JSON.parse(JSON.stringify(state))).toEqual(state);
});
```
6. **Use `silentRun()` in saga tests** — Suppresses timeout warnings for faster tests.
7. **Review refactor cleanup** — When a change moves, renames, or splits modules,
inspect the old paths from the diff. Remove old modules that are now only
one-line re-exports, import/export proxies, or delegate-only wrappers, or add
an adjacent compatibility-shim comment that states the consumer/release window
and sunset/removal condition. Summaries should call out either “no pass-through
wrappers” or list the justified shims.
8. **File naming convention** — Test files live next to the code: `my-slice.test.ts`, `my-saga.test.ts`.
9. **Run the architecture-backed test examples check** — Changes to tests,
README snippets, docs, or skills should run `npm run validate:architecture`.
This command includes ESLint-backed
test-pattern rules for selector tests and `typed-redux-saga` mocks. A failure
points at the source test file or Markdown fence and includes `Why:` plus
`How to fix:` guidance. Fix selector-test failures by using
`selectFoo.select(mockState, ...args)`; fix `typed-redux-saga` mock failures
by preserving the `Array.isArray(fnOrDescriptor)` branch for tuple call
descriptors. Mark intentionally bad Markdown teaching examples as wrong/bad
rather than leaving them indistinguishable from recommended snippets.