Imported from prowler-cloud/prowler (
skills/vitest/SKILL.md). Install upstream withnpx skills add prowler-cloud/prowler --skill vitest. Copyright stays with the author (Apache-2.0).
For E2E tests: Use
prowler-test-uiskill (Playwright). This skill covers unit/integration tests with Vitest + React Testing Library.
Prowler UI Test Projects (ui/vitest.config.ts)
| Project | Files | Environment | Setup |
|---|---|---|---|
unit |
**/*.test.{ts,tsx} (excludes tests/**, *.integration.test.*) |
jsdom, no React Compiler | vitest.setup.ts (jest-dom matchers, storage mock) |
integration |
**/*.integration.test.{ts,tsx} |
Vitest browser mode, Playwright Chromium, React Compiler | vitest.integration.setup.ts (MSW worker, globals.css, mocks for @/auth.config, next/cache, server-only) |
- Tests are co-located next to the code (
foo.ts->foo.test.ts); shared fixtures live inui/__tests__/. - Config sets
globals,restoreMocks,mockReset,unstubEnvs,unstubGlobals: do not addafterEach(vi.restoreAllMocks)boilerplate. - Integration tests import
page/userEventfromvitest/browser, render with@/__tests__/render-browser, and mock HTTP with MSW (ui/__tests__/msw/), notvi.mockof fetch.
Test Structure (REQUIRED)
Use Given/When/Then (AAA) pattern with comments:
it("should update user name when form is submitted", async () => {
// Given - Arrange
const user = userEvent.setup();
const onSubmit = vi.fn();
render(<UserForm onSubmit={onSubmit} />);
// When - Act
await user.type(screen.getByLabelText(/name/i), "John");
await user.click(screen.getByRole("button", { name: /submit/i }));
// Then - Assert
expect(onSubmit).toHaveBeenCalledWith({ name: "John" });
});
Describe Block Organization
describe("ComponentName", () => {
describe("when [condition]", () => {
it("should [expected behavior]", () => {});
});
});
Group by behavior, NOT by method.
Query Priority (REQUIRED)
| Priority | Query | Use Case |
|---|---|---|
| 1 | getByRole |
Buttons, inputs, headings |
| 2 | getByLabelText |
Form fields |
| 3 | getByPlaceholderText |
Inputs without label |
| 4 | getByText |
Static text |
| 5 | getByTestId |
Last resort only |
// ✅ GOOD
screen.getByRole("button", { name: /submit/i });
screen.getByLabelText(/email/i);
// ❌ BAD
container.querySelector(".btn-primary");
userEvent over fireEvent (REQUIRED)
// ✅ ALWAYS use userEvent
const user = userEvent.setup();
await user.click(button);
await user.type(input, "hello");
// ❌ NEVER use fireEvent for interactions
fireEvent.click(button);
Async Testing Patterns
// ✅ findBy for elements that appear async
const element = await screen.findByText(/loaded/i);
// ✅ waitFor for assertions
await waitFor(() => {
expect(screen.getByText(/success/i)).toBeInTheDocument();
});
// ✅ ONE assertion per waitFor
await waitFor(() => expect(mockFn).toHaveBeenCalled());
await waitFor(() => expect(screen.getByText(/done/i)).toBeVisible());
// ❌ NEVER multiple assertions in waitFor
await waitFor(() => {
expect(mockFn).toHaveBeenCalled();
expect(screen.getByText(/done/i)).toBeVisible(); // Slower failures
});
Mocking
// Basic mock
const handleClick = vi.fn();
// Mock with return value
const fetchUser = vi.fn().mockResolvedValue({ name: "John" });
// Module mock (hoisted) - common for server actions and next/* modules
vi.mock("@/actions/providers", () => ({ getProviders: vi.fn() }));
vi.spyOn vs vi.mock
| Method | When to Use |
|---|---|
vi.spyOn |
Observe or override one export/method |
vi.mock |
Replace a module boundary (server actions, next/navigation, next-auth) |
Common Matchers
// Presence
expect(element).toBeInTheDocument();
expect(element).toBeVisible();
// State
expect(button).toBeDisabled();
expect(input).toHaveValue("text");
expect(checkbox).toBeChecked();
// Content
expect(element).toHaveTextContent(/hello/i);
expect(element).toHaveAttribute("href", "/home");
// Functions
expect(fn).toHaveBeenCalledWith(arg1, arg2);
expect(fn).toHaveBeenCalledTimes(2);
What NOT to Test
// ❌ Internal state
expect(component.state.isLoading).toBe(true);
// ❌ Third-party libraries
expect(axios.get).toHaveBeenCalled();
// ❌ Static content (unless conditional)
expect(screen.getByText("Welcome")).toBeInTheDocument();
// ✅ User-visible behavior
expect(screen.getByRole("button")).toBeDisabled();
Commands
cd ui && pnpm run test # vitest run (all projects, single run)
cd ui && pnpm run test:unit # unit project only
cd ui && pnpm run test:integration # browser project (needs Playwright Chromium: pnpm run test:e2e:install)
cd ui && pnpm run test:watch # watch mode
cd ui && pnpm run test:coverage # v8 coverage
cd ui && pnpm exec vitest run --project unit lib/findings-sort.test.ts # filter by path