@thepalaceproject/circulation-admin 1.43.0 → 1.44.0-post.4

package/CLAUDE.md

@@ -16,13 +16,14 @@ npm run dev-server -- --env=backend=https://your-cm-url  # Dev server against re
 npm run prod                   # Production build
 npm run lint                   # Run ESLint (lint:js) + sass-lint
 npm run lint:js                # Run ESLint over the whole tree (eslint . --max-warnings 0)
-npm test                       # Full test suite (mocha legacy + jest)
-npm run test-jest              # Jest tests only
-npm run test-jest-file <path>  # Single jest test: npm run test-jest-file tests/jest/components/MyTest.test.tsx
-npm run test-file-ts <path>    # Single mocha test: npm run test-file-ts src/components/__tests__/MyTest-test.tsx
+npm test                       # Full jest suite
+npm run test-jest-file <path>  # Single test: npm run test-jest-file tests/jest/components/MyTest.test.tsx
+npm run coverage               # Test suite with coverage (what CI runs); writes coverage/jest/lcov.info
 npm run dev-test-axe           # Dev build with react-axe accessibility checking (output in browser console)
 ```
 
+Run a single file with `npx jest --testPathPattern='components/MyTest\.test'`.
+
 The dev server can also read the backend URL from `.env` or `.env.local` with `BACKEND=https://...`.
 
 ## Architecture
@@ -62,11 +63,31 @@ The dev server can also read the backend URL from `.env` or `.env.local` with `B
 
 ## Testing
 
-**Two test systems coexist:**
+Every test runs under one jest config (`jest.config.js`). Tests live in `tests/jest/`, mirroring the `src/` tree, and are named `*.test.{ts,tsx}` — `testMatch` only picks up that directory, so `src/` holds no test code. Shared fixture data (`genreData`, `classificationsData`) is in `tests/jest/fixtures/`.
+
+Tests are written with React Testing Library (+ `@testing-library/user-event`); `@testing-library/jest-dom` matchers are registered globally in `tests/jest/jest-setup.ts`. For API mocking the tree uses both MSW and `fetch-mock-jest` — `fetch-mock-jest` is the more common choice, MSW mainly where a request handler is clearer. Follow whichever the neighboring tests use.
+
+Helpers in `tests/jest/testUtils/`:
+
+- `withProviders.tsx` — `renderWithProviders()` and `componentWithProviders()` wrap a component in Redux, app Context, and QueryClient. Use these for anything touching the store.
+- `renderWithContext.tsx` — lighter: app Context only.
+- `formDataShim.ts` — `installFormDataShim()`; the reusable `<Form>` submit path needs it because undici's `FormData` rejects form elements.
+
+**Writing tests — the traps that actually bite:**
+
+- Render the **connected default export**, not the unconnected named export, or `mapStateToProps`/`mapDispatchToProps` never run and their coverage is lost. Mocking a connected child in a parent's test drops that child's wiring the same way — cover the child in its own test.
+- Unhandled rejections fail the run: stub `fetch` and `await` a `findBy*` so on-mount fetches settle before the test ends.
+- `EditableInput` renders label and input as siblings with no `htmlFor`, so reach for `getByText`, not `getByLabelText`.
+- Mock react-router's `Link` as a `<div>`, not an `<a>` (jsx-a11y). Mock default exports as `{__esModule: true, default: ...}`.
+
+**Environment:** `jest-fixed-jsdom` restores Node's `fetch`/`Response` globals so MSW can intercept them; `jest.polyfills.js` runs first via `setupFiles`. `testEnvironmentOptions.customExportConditions: [""]` keeps jsdom's default `["browser"]` condition from resolving ESM-only dependency bundles that ts-jest cannot transform. `moduleNameMapper` stubs asset, style, and markdown imports out to `tests/__mocks__/`.
+
+**Coverage:** `npm run coverage` writes `coverage/jest/lcov.info`, uploaded to Codecov under the `jest` flag (`threshold: 0.2%`). There is no local coverage gate — Codecov and review are the enforcement. Two config constraints, both of which silently inflate the number if broken:
 
-1. **Jest** (for all new tests): Tests in `tests/jest/` mirroring `src/` structure. Uses React Testing Library, jest-dom, and MSW for API mocking. Test utilities in `tests/jest/testUtils/withProviders.tsx` provide `renderWithProviders()` and `componentWithProviders()` to wrap components with Redux, Context, and QueryClient.
+- `collectCoverageFrom` must stay at the _top level_ of `jest.config.js`; jest reads it off the global config, so nesting it leaves it globally undefined and every executed file gets instrumented, `tests/` helpers included.
+- `roots` must keep `<rootDir>/src` so `collectCoverageFrom` can discover source files no test imports. Otherwise they are omitted from the report rather than counted as uncovered.
 
-2. **Mocha** (legacy): Tests in `src/*/__tests__/` directories. Uses Enzyme with React 16 adapter. Do not add new mocha tests.
+**End-to-end:** Nightwatch/selenium tests live in `tests/browser/` (config: `nightwatch.json`, run via `npm run test-browser`). They need credentials and a selenium install, are not part of `npm test`, and do not run in CI; see `tests/browser/README.md`.
 
 ## Code Style
 

package/README.md

@@ -126,17 +126,23 @@ In order to run the app with `react-axe`, run `npm run dev-test-axe`. This will
 
 ### Unit Tests
 
-Like the codebase, all the unit tests are written in Typescript. Tests are written for all React components as well as redux and utility functions. Older tests are run using mocha and these tests can be found in the `__tests__` folders littered throughout the `src` tree. All new tests should be written using jest and placed in the `tests/jest` directory. The directory structure in `tests/jest` should mirror the structure in `src`.
+Like the codebase, the unit tests are written in Typescript. They cover React components as well as redux and utility functions. Tests run under jest and live in the `tests/jest` directory, whose structure mirrors `src`; each file is named `*.test.ts` / `*.test.tsx`, and shared fixture data lives in `tests/jest/fixtures`.
 
-To run the tests, perform `npm test`.
+Components are tested with [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/), which drives components the way a user does — query by role and text, not by internal structure. `tests/jest/testUtils` has helpers for the common setup: `renderWithProviders()` wraps a component in the Redux store, app context, and QueryClient, and `renderWithContext()` does app context alone. Network calls are stubbed with `fetch-mock-jest` or MSW; the tests around the one you are writing will show which.
 
-We use GitHub Actions for continuous integration. Any pull requests submitted must have tests and those tests must pass on GitHub Actions.
+```bash
+npm test                       # the whole suite
+npm run test-jest-file <path>  # a single file
+npm run coverage               # the suite with a coverage report, written to coverage/jest/lcov.info
+```
+
+We use GitHub Actions for continuous integration. Any pull requests submitted must have tests and those tests must pass on GitHub Actions. Coverage is reported to Codecov, which will comment on the pull request if it drops.
 
 ### Nightwatch
 
-There are end-to-end tests that run on Nightwatch. This selenium-based test runner allows us to include integration tests for logging into the admin and clicking through different pages.
+There are end-to-end tests that run on Nightwatch. This selenium-based test runner allows us to include integration tests for logging into the admin and clicking through different pages. They live in `tests/browser` and are separate from the jest suite — `npm test` does not run them.
 
-To set up credentials and run the tests, check out the [README](/tests/README.md) in `/tests/.
+To set up credentials and run the tests, check out the [README](/tests/browser/README.md) in `/tests/browser`.
 
 ## Patron Blocking Rules — Keeping Documentation in Sync