component testing

intent

write and review unit, component, and light integration tests for frontend code using user-centric assertions and accessible queries. use this skill when testing pure logic (functions, hooks, composables), component contracts (props, emits, callbacks), user interactions, state transitions (loading, error, empty), and regression scenarios. skip this for cross-page real-browser flows (use e2e testing instead) or for test strategy/planning (use testing layer planning first). this skill focuses on tests that live close to the code they verify and validate behavior users can perceive.

inputs

• test framework: vitest, jest, mocha, or similar (set NODE_ENV=test if needed)
• testing library: @testing-library/react, @vue/test-utils, or equivalent for your framework
• user-event library: @testing-library/user-event for simulating keyboard and pointer interactions (not fireEvent)
• mock library: vitest.mock(), jest.mock(), or equivalent (already in most projects)
• component source code: the file(s) you're testing, with clear props/emits/callbacks defined
• design system or ui library: if using Material-UI, Ant Design, Shadcn, etc., know which accessible queries are stable (avoid mocking internals)
• api mocks or fixtures: sample data reflecting real business scenarios (user objects, error shapes, pagination responses)
• test environment setup: ensure jsdom or happy-dom is configured in vitest.config.ts or jest.config.js; accessibility tree (a11y) must be available
• git history (for regressions): if fixing a bug, have the issue number and repro steps available

procedure

1. determine test layer first

   • unit: pure functions, hooks, composables, utils, schema validation. test inputs and outputs only.
   • component: props, emits, callbacks, user interactions, loading/error/empty states, permission/disabled states, keyboard focus. mock external dependencies (apis, routers, stores).
   • light integration: form + api mock + router/store/provider context. keep to under 3 logical "modules" cooperating; if more complex, split or use e2e.
   • if layer is unclear, do test layer planning first. cross-page journeys and real-browser flows belong in e2e, not here.

2. prioritize user-perceivable behavior over implementation details

   • structure each test with clear arrange / act / assert: prepare data and render, execute user action, assert visible result or public contract.
   • use accessible queries: getByRole(), getByLabelText(), getByPlaceholderText(), getByText(). fall back to data-testid only when no stable semantic query exists.
   • test names should describe user scenarios ("submits form when all fields filled") not function names ("calls handleSubmit").
   • example (react):

     import { render, screen } from "@testing-library/react";
     import userEvent from "@testing-library/user-event";
     import { SearchBox } from "./SearchBox";
     
     test("submits the entered keyword when user clicks search", async () => {
       const user = userEvent.setup();
       const onSearch = vi.fn();
     
       render(<SearchBox onSearch={onSearch} />);
     
       await user.type(screen.getByRole("searchbox", { name: /keyword/i }), "orders");
       await user.click(screen.getByRole("button", { name: /search/i }));
     
       expect(onSearch).toHaveBeenCalledWith("orders");
     });
     

3. for vue components, use accessible queries and explicit emits

   • prefer getByRole(), getByText(), findByRole() over implementation details.
   • use data-testid only when no semantic query is stable (e.g., custom icon component with no text).
   • assert emits via wrapper.emitted() and check event payload shape.
   • example (vue):

     import { mount } from "@vue/test-utils";
     import UserMenu from "./UserMenu.vue";
     
     test("emits logout event when logout item is clicked", async () => {
       const wrapper = mount(UserMenu, {
         props: { userName: "Ada" },
       });
     
       const logoutButton = wrapper.get('[data-testid="logout-button"]');
       await logoutButton.trigger("click");
     
       expect(wrapper.emitted("logout")).toHaveLength(1);
     });
     

4. control mock boundaries strictly

   • mock external calls (http, timers, routing, browser apis, external stores). do not mock the component being tested or its internal logic.
   • for design system components (button, input, modal), mock sparingly. preserve accessible behavior and avoid mocking internals that break a11y tree.
   • mock data should reflect real business scenarios (user objects with id, name, role; api error responses with status and message). avoid random or test-only strings.
   • shared fixtures should be readable. for complex objects, use a builder or factory to set defaults; each test specifies only fields relevant to that scenario.
   • when mocking network responses, mock the user-visible result shape and error shapes, not backend implementation details.
   • example:

     vi.mock("../api/users", () => ({
       fetchUsers: vi.fn(async () => [
         { id: "1", name: "Ada", role: "admin" },
         { id: "2", name: "Bob", role: "user" },
       ]),
     }));
     

5. cover critical state paths

   • default render (no props, no interaction).
   • user interaction (clicks, typing, form submission, keyboard nav).
   • loading state (while data is fetching).
   • empty state (no results, no items).
   • error state (api failure, validation error, network timeout).
   • permission or disabled state (user lacks access, button is disabled).
   • keyboard interaction and focus behavior (if applicable).
   • at least one happy-path and one sad-path test per component.

6. keep tests maintainable

   • extract repeated render setup into a setup() helper. return the user object and all mocks so tests remain explicit.
   • do not hide the core action and assertion inside helpers. helpers should only reduce boilerplate, not obscure what the test does.
   • use meaningful variable names (onSubmit, mockApiCall, not fn1, fn2).
   • keep test files colocated with component source (same directory or tests folder per project convention).
   • example:

     function setup() {
       const user = userEvent.setup();
       const onSubmit = vi.fn();
       render(<ProfileForm onSubmit={onSubmit} />);
       return { user, onSubmit };
     }
     
     test("saves profile when form is submitted", async () => {
       const { user, onSubmit } = setup();
       await user.type(screen.getByLabelText(/name/i), "Ada");
       await user.click(screen.getByRole("button", { name: /save/i }));
       expect(onSubmit).toHaveBeenCalled();
     });
     

7. for regression tests, prove the problem first

   • write a minimal test that fails before the fix. the failure message should point to user behavior or public contract, not import errors or test timing.
   • after fix, keep the regression test in the suite. do not rely on manual qa to catch the same issue twice.
   • example: "test fails with 'expected onSubmit to be called but was not' before fix, passes after fix."

decision points

• if layer is unclear (unit vs component vs integration): stop and do test layer planning first. do not guess.
• if testing a hook or composable: write a unit test in isolation, or use a testing library helper (react-hooks-testing-library, @vue/test-utils). do not force it into a component test.
• if no stable accessible query exists (e.g., custom icon with no aria-label): use data-testid and document why semantic query is not viable.
• if async behavior is needed: use findBy* or waitFor(), never fixed timeouts. if timeout occurs, increase the default (screen.getByRole has a 1s default; adjust in test runner config if test legitimately takes longer).
• if mocking a design system component's internal dom: reconsider. if you must, verify the mock preserves a11y attributes (role, aria-label, etc.) so queries still work.
• if test passes but user reports the bug in production: check that the test actually exercises the code path (not shadowed by a conditional) and that mock data matches production shapes.
• if snapshot assertions are tempting: use them only for static output (error message text, static html). never as the primary assertion for interactive components; snapshot tests break too easily and hide real behavior changes.
• if tests share mutable state or fixtures across cases: isolate each test. move shared setup into per-test setup() calls or beforeEach, and reset mocks between tests (vitest/jest do this by default in isolation mode).

output contract

• location: test files colocated with component source (e.g., SearchBox.test.tsx next to SearchBox.tsx, or in tests/SearchBox.test.tsx per project convention).
• format: one test file per component, or grouped by feature if multiple small related components exist.
• coverage: each test is a single scenario (one user action, one assertion). multiple scenarios = multiple tests, not multiple assertions per test.
• pass criteria: run npm test or yarn test (or project-specific test command). all tests pass. failure messages clearly indicate which user action or component contract failed, not implementation details.
• assertions: use expect() from vitest/jest. verify callbacks were called with correct args, emits contain correct payload, dom reflects user action, error/loading/empty states render.

outcome signal

• tests pass: npm test exits with status 0. all tests run successfully.
• test names describe behavior: reading test names tells you what the component does without reading assertions.
• failure messages are actionable: when a test fails, the error message points to a user action or public contract (e.g., "expected onSubmit to be called with {email: 'test@example.com'} but was not called") not implementation details (e.g., "setState was not called").
• new contributors understand tests quickly: setup() functions and test structure follow arrange/act/assert. no hidden magic or complex mocking.
• regressions stay fixed: bug-fix tests remain in the suite. if the same bug resurfaces, tests catch it before production.