From f3fae6deed2d63105c73fb639468c4ef5830673a Mon Sep 17 00:00:00 2001 From: "moxie-docs[bot]" <287554421+moxie-docs[bot]@users.noreply.github.com> Date: Fri, 31 Jul 2026 05:02:51 +0000 Subject: [PATCH] docs: moxie-docs/testing/frontend-src-app-test.md --- moxie-docs/testing/frontend-src-app-test.md | 86 +++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 moxie-docs/testing/frontend-src-app-test.md diff --git a/moxie-docs/testing/frontend-src-app-test.md b/moxie-docs/testing/frontend-src-app-test.md new file mode 100644 index 0000000..14aed3a --- /dev/null +++ b/moxie-docs/testing/frontend-src-app-test.md @@ -0,0 +1,86 @@ +# Frontend Testing (Create React App + React Testing Library) + +This area documents the frontend test setup and conventions for the CRA-based app. It explains how tests are discovered and executed, the libraries in use, and how to extend the single existing test into a maintainable test suite. + +## Architecture + +- Test runner and harness: provided by `react-scripts test` (Jest under the hood) configured via CRA. +- Assertion and DOM matchers: `@testing-library/jest-dom` augments Jest’s `expect` with DOM-specific matchers. +- Rendering and queries: `@testing-library/react` drives component rendering and queries into the virtual DOM. +- User interaction helpers: `@testing-library/user-event` for realistic event simulation. +- Test discovery: CRA/Jest automatically picks up files named `*.test.js`, `*.test.jsx`, `*.spec.js`, or `*.spec.jsx` anywhere under `frontend/src/`. +- Control entry points: + - CLI: `npm test` or `yarn test` executes `react-scripts test` with watch mode by default in interactive TTY. + - Tests import components from `src/` and render with Testing Library to assert DOM output and behavior. + +## frontend/package.json + +Responsibility +- Declares testing dependencies and the script used to run tests. + +Key contents +- Scripts: + - `test`: `react-scripts test` (Jest runner with CRA defaults) + - `start`, `build`, `eject` are unrelated to tests but share CRA tooling. +- Dependencies used by tests: + - `@testing-library/jest-dom`: `^5.17.0` + - `@testing-library/react`: `^13.4.0` + - `@testing-library/user-event`: `^13.5.0` +- ESLint config extends `react-app/jest`, enabling Jest globals and Testing Library lint rules where applicable. + +How it fits together +- Running `npm test` uses the CRA preset to set up Jest, load `@testing-library/jest-dom` automatically (via CRA’s default Jest setup), and execute any matching test files under `src/`. + +Operational notes +- Watch mode: In interactive terminals, `react-scripts test` runs in watch mode; press `a` to run all tests, `p` to filter by filename, `t` to filter by test name. +- CI mode: When `CI=true` is set in the environment, CRA disables watch mode and treats warnings as failures during build (not test). For tests, it runs once and exits. + +## frontend/src/App.test.js + +Responsibility +- Provides a smoke test that verifies the `App` component renders a link with text matching `/learn react/i`. + +Behavior +- Renders `` using `render` from `@testing-library/react`. +- Uses `screen.getByText(/learn react/i)` to query for the element. +- Asserts `expect(linkElement).toBeInTheDocument()` using `@testing-library/jest-dom`. + +Contracts and assumptions +- Imports `App` from `./App` and assumes `App` renders text matching “learn react” case-insensitively. +- Fails if the visible text changes or is removed, which can make the test brittle if the UI copy evolves. + +Example structure to extend +- To add more tests, create files like `src/components/Button/Button.test.jsx` or colocate next to components, e.g., `src/components/Button.test.jsx`. CRA will discover both. + +## Running, Extending, and Organizing Tests + +Running tests +- Interactive: from `frontend/`, run `npm test` to start Jest in watch mode. +- Single run: `CI=true npm test` runs once and exits (useful for CI scripts). +- Filter by filename: after starting watch mode, press `p` and type part of the test file path. +- Filter by test name: press `t` and type part of the `test(...)` or `it(...)` name. + +Adding tests +- File naming: use `*.test.js(x)` or `*.spec.js(x)` under `src/`. +- Typical test pattern: + - Render the component with `render(...)`. + - Query using `screen.getByRole`, `screen.getByText`, etc. Prefer role-based queries for resilience. + - Interact with `userEvent` for realistic user flows. + - Assert using `@testing-library/jest-dom` matchers like `toBeInTheDocument`, `toHaveTextContent`, `toBeDisabled`, etc. + +Organizing tests +- Co-locate tests with components: keep `Component.jsx` next to `Component.test.jsx` to encourage maintenance with code changes. +- Use a shared test utils file (e.g., `src/test-utils.jsx`) if you need common render wrappers (providers, routers). Import it in tests as needed. Note: this repository does not currently include such a file—add it under `src/` if required. + +Common patterns +- Async UI: use `findBy...` queries or `waitFor` when asserting results after async effects. +- Accessibility-first queries: use `getByRole({ name: /label/i })` rather than brittle `getByText` when possible. +- User flows: prefer `userEvent` over `fireEvent` to simulate typing, clicks, and tab navigation. + +## Gotchas + +- Text-coupled assertions: The current `App.test.js` asserts on the literal text `/learn react/i`. UI copy changes will break this test. Prefer role and accessible name queries (e.g., `getByRole('link', { name: /learn react/i })`) or data-driven selectors where appropriate. +- Test discovery location: Jest via CRA only discovers tests under `src/`. Placing tests outside `frontend/src/` will not run. +- ESM/CommonJS interop: CRA config handles most cases; avoid custom Jest config unless ejecting. If you eject, you must maintain Jest config yourself. +- Environment differences: In CI (`CI=true`), watch mode is disabled and some timing may differ. Write tests that do not rely on watch-specific behavior. +- DOM matchers availability: `@testing-library/jest-dom` matchers (e.g., `toBeInTheDocument`) are available because CRA’s Jest setup imports it. If tests run outside CRA defaults (after eject), ensure `setupTests.js` imports `@testing-library/jest-dom` explicitly. \ No newline at end of file