docs: document frontend testing conventions

[nitrobass24]

Summary

Documents the frontend-test conventions that aren't obvious from the config or existing docs — the ones that cost real time to (re)discover while building out coverage during the #1963 table decomposition.

AGENTS.md — new Frontend tests subsection

• Ship colocated *.test.ts(x); extract logic into hooks/lib so it's unit-testable without mounting the whole tree.
• Vitest is globals: false + jsdom + no setup file → import test globals from "vitest", no jest-dom matchers, assert with plain DOM.
• Mounting components with effects: mock boundaries and return stable singletons (fresh objects per render loop effects → OOM the worker); vi.hoisted() for mock values in vi.mock factories.
• jsdom renders zero virtual rows and does no real layout/scroll/drag → unit-test the extractable logic and manually smoke anything visual/interactive; a green suite ≠ full coverage.

CONTRIBUTING.md — one expectation bullet

• Frontend changes should ship with vitest specs; behavior jsdom can't render needs a manual smoke.

Why here

CONTRIBUTING.md already covers the mechanics (run commands, colocation, CI) and explicitly defers "deeper conventions" to AGENTS.md/CLAUDE.md — so the how lives in AGENTS.md (note: CLAUDE.md is a symlink to AGENTS.md, so this updates both).

Testing

Docs-only — no code paths affected.

Opened as draft for wording review.

Summary by CodeRabbit

• Documentation
  • Updated contributor guidelines to include frontend testing standards and manual testing requirements for complex UI interactions.

[coderabbitai]

Walkthrough

The PR updates frontend testing documentation to establish consistent Vitest standards. CONTRIBUTING.md mandates vitest specs for frontend changes and manual smoke testing for jsdom-incompatible scenarios. web/AGENTS.md provides detailed guidance on Vitest configuration, assertion patterns, mocking strategies, and jsdom constraints.

Changes

Frontend Testing Guidelines

Layer / File(s)	Summary
Frontend Testing Conventions Documentation CONTRIBUTING.md, web/AGENTS.md	CONTRIBUTING.md requires vitest specs and manual smoke testing for virtualization, drag-and-drop, and scroll. web/AGENTS.md documents Vitest configuration (globals: false, explicit imports), plain DOM assertions without jest-dom, mocking patterns with vi.hoisted(), and guidance on unit-testing versus manual testing given jsdom layout limitations.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• autobrr/qui#1995: Directly builds on the retrieved PR's restructuring of web/AGENTS.md by adding detailed Vitest frontend test-suite requirements and jsdom/manual smoke-testing notes to the same file.
• autobrr/qui#1936: Updates CONTRIBUTING.md and web/AGENTS.md to require Vitest specs and manual jsdom smoke testing, refining the same frontend Vitest test infrastructure introduced in the retrieved PR.

Suggested labels

tests, chore

Poem

🐰 New tests take shape with Vitest's care,
Plain assertions declared and laid bare,
When jsdom can't dance, we test by hand,
Drag and scroll, where manual tests stand.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and accurately summarizes the main change: documenting frontend testing conventions in AGENTS.md and CONTRIBUTING.md.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/frontend-test-conventions

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@AGENTS.md`:
- Around line 117-128: Update AGENTS.md to point the example hook path to an
existing test pattern (replace the non-existent reference to
web/src/hooks/torrent-table/ with web/src/hooks/useInstanceMetadata.test.tsx)
and adjust the guidance text so assertions and mocking advice match our actual
tests: explicitly state Vitest uses environment: "jsdom", globals: false, no
setup files, require importing test globals (describe, it, expect, vi), forbid
jest-dom matchers (e.g., toBeInTheDocument) and show using plain DOM checks
(textContent, getAttribute, expect(node).toBeNull()), and clarify the
vi.hoisted() recommendation (note use only when a value is referenced inside
vi.mock factories or soften to “prefer vi.hoisted() for stable singletons”);
keep the doc examples and wording aligned with existing repo patterns and tests
such as useInstanceMetadata.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: f5200d08-c8f0-46a2-8658-016a40d1643b

📥 Commits

Reviewing files that changed from the base of the PR and between 719866b and 53aef3e.

📒 Files selected for processing (2)

• AGENTS.md
• CONTRIBUTING.md

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Verify Vitest configuration and example path reference

echo "=== Checking Vitest configuration ==="
if [ -f "web/vitest.config.ts" ] || [ -f "web/vitest.config.js" ]; then
  echo "Found Vitest config:"
  fd -t f 'vitest.config\.(ts|js)' web/ --exec cat {}
else
  echo "No vitest.config found in web/"
fi

echo -e "\n=== Checking for setup files ==="
fd -t f 'setup.*\.(ts|js)' web/ --exec echo "Found: {}"

echo -e "\n=== Checking globals configuration ==="
rg -A 5 "globals:" web/vitest.config.ts web/vitest.config.js 2>/dev/null || echo "No globals config found"

echo -e "\n=== Checking for jest-dom usage ==="
rg -n "`@testing-library/jest-dom`" web/src/ 2>/dev/null || echo "No jest-dom imports found"

echo -e "\n=== Verifying example path exists ==="
if [ -d "web/src/hooks/torrent-table/" ]; then
  echo "✓ web/src/hooks/torrent-table/ exists"
  fd -t f . web/src/hooks/torrent-table/ --exec echo "  {}"
else
  echo "✗ web/src/hooks/torrent-table/ does not exist"
fi

echo -e "\n=== Checking for vi.hoisted() usage in tests ==="
rg -n "vi\.hoisted\(" web/src/ --glob '*.test.ts*' -C 2 | head -20 || echo "No vi.hoisted() usage found in tests"

echo -e "\n=== Sample test file structure ==="
fd -t f '\.test\.tsx?$' web/src/ | head -3 | while read -r file; do
  echo "File: $file"
  head -20 "$file"
  echo "---"
done

Repository: autobrr/qui

Length of output: 3632

---

Fix AGENTS.md frontend testing guidance (wrong example path + align test-mocking assertions)

In AGENTS.md (lines 117-128), web/src/hooks/torrent-table/ is referenced but the directory doesn’t exist—update the example to a real hook/unit-test pattern (e.g., web/src/hooks/useInstanceMetadata.test.tsx).

The Vitest config in web/vitest.config.ts matches the doc’s setup (environment: "jsdom", globals: false, and no setupFiles/setupFilesAfterEnv). No @testing-library/jest-dom imports were found in web/src/; if keeping the “no jest-dom matchers” rule, also ensure matcher usage like toBeInTheDocument doesn’t appear. The vi.hoisted() recommendation should be backed by an existing repo pattern (or softened) based on actual test code.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@AGENTS.md` around lines 117 - 128, Update AGENTS.md to point the example hook
path to an existing test pattern (replace the non-existent reference to
web/src/hooks/torrent-table/ with web/src/hooks/useInstanceMetadata.test.tsx)
and adjust the guidance text so assertions and mocking advice match our actual
tests: explicitly state Vitest uses environment: "jsdom", globals: false, no
setup files, require importing test globals (describe, it, expect, vi), forbid
jest-dom matchers (e.g., toBeInTheDocument) and show using plain DOM checks
(textContent, getAttribute, expect(node).toBeNull()), and clarify the
vi.hoisted() recommendation (note use only when a value is referenced inside
vi.mock factories or soften to “prefer vi.hoisted() for stable singletons”);
keep the doc examples and wording aligned with existing repo patterns and tests
such as useInstanceMetadata.

[nitrobass24]

Rebased onto develop to clear the conflict; force-pushed.

develop's #1995 rewrote the root AGENTS.md into a concise form and moved frontend-specific rules into web/AGENTS.md, so this PR's additions to the old long-form root doc collided wholesale.

Resolved by keeping develop's rewritten root AGENTS.md and relocating the frontend-test conventions into web/AGENTS.md (which only carried a one-line stub) — that's where frontend rules now live. The CONTRIBUTING.md bullet auto-merged cleanly. Net change vs develop: web/AGENTS.md (+9), CONTRIBUTING.md (+1).

A fresh pull/checkout of this branch is needed.

[coderabbitai]

🧹 Nitpick comments (3)

web/AGENTS.md (3)

19-19: ⚡ Quick win

Add cleanup to the import guidance.

Since globals: false disables auto-cleanup (confirmed in SeasonPackCategoryRulesEditor.test.tsx), developers need to import and call cleanup explicitly in afterEach. Consider adding cleanup to the listed imports from @testing-library/react.

📝 Suggested addition

-  - Import test globals explicitly: `import { describe, it, expect, vi } from "vitest"`; use `render` / `renderHook` / `act` from `@testing-library/react`.
+  - Import test globals explicitly: `import { describe, it, expect, vi } from "vitest"`; use `render` / `renderHook` / `act` / `cleanup` from `@testing-library/react`. Call `cleanup()` in `afterEach` since auto-cleanup is disabled.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@web/AGENTS.md` at line 19, Update the import guidance to include cleanup:
instruct developers to import cleanup from "`@testing-library/react`" alongside
render / renderHook / act (e.g., import { render, renderHook, act, cleanup }
from "`@testing-library/react`") and remind them to call cleanup in an afterEach
(e.g., afterEach(() => cleanup())) so tests with globals: false properly
teardown DOM between tests; reference the symbols render, renderHook, act,
cleanup, and afterEach in the guidance.

Source: MCP tools

---

22-22: ⚡ Quick win

Clarify "zero virtual rows" phrasing for precision.

The phrase "it renders zero virtual rows" could be misread. The intended meaning appears to be that jsdom natively cannot exercise virtualization due to lack of layout measurements, which would result in no rows being rendered by an unmocked virtualizer. The mock in TorrentTableOptimized.smoke.test.tsx works around this by deterministically rendering all rows. Consider rephrasing for clarity.

📝 Suggested clarification

-- jsdom does no real layout, scroll, or pointer/drag work — it renders **zero virtual rows** and cannot exercise virtualization, dnd-kit, or scroll restoration. Unit-test the extractable logic (reorder math, row-height mapping, handler wiring) and **manually smoke** anything visual or interactive; a green suite is not full coverage. Run targeted with `cd web && npx vitest run <path>`; CI runs the full suite via `make test-frontend`.
+- jsdom does no real layout, scroll, or pointer/drag work — **virtualizers return empty results** without mocking and cannot exercise virtualization, dnd-kit, or scroll restoration. Unit-test the extractable logic (reorder math, row-height mapping, handler wiring) and **manually smoke** anything visual or interactive; a green suite is not full coverage. Run targeted with `cd web && npx vitest run <path>`; CI runs the full suite via `make test-frontend`.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@web/AGENTS.md` at line 22, Rephrase the sentence that currently reads "it
renders **zero virtual rows**" to clearly state that jsdom provides no
layout/measurement APIs so unmocked virtualizers will render no rows (e.g.,
"jsdom provides no layout measurements, so virtualizers typically render nothing
unless mocked"); mention the existing test workaround in
TorrentTableOptimized.smoke.test.tsx which deterministically renders all rows to
exercise logic. Update AGENTS.md accordingly so the intent and the test
workaround are unambiguous.

Source: MCP tools

---

51-53: 💤 Low value

Optional: Consider varying sentence openings.

Static analysis flagged three successive sentences starting with "Add" (lines 51-53). The parallel structure aids scannability in this procedural checklist, so the repetition is arguably beneficial. If you prefer variety, consider rephrasing one step.

📝 Optional rephrase example

 1. Add all 10 namespace JSON files under `web/src/i18n/locales/<lang>/`.
 2. Add code to `supportedLanguages` and display name to `languageNames` in `web/src/i18n/index.ts`.
-3. Add/adapt a locale coverage script if the locale is not `zh-CN`.
+3. Create or adapt a locale coverage script if the locale is not `zh-CN`.
 4. Run `pnpm check:i18n`.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@web/AGENTS.md` around lines 51 - 53, The three checklist items in AGENTS.md
all start with the verb "Add", making the openings repetitive; update one of the
three bullets (the lines that list adding namespace JSON files, updating
supportedLanguages/languageNames, and adapting the locale coverage script) to
use a different opening verb or phrasing (e.g., "Place", "Update", "Adapt", or
rephrase as "Include X in Y") so the list keeps parallel structure but avoids
identical sentence starts while preserving the original meaning.

Source: Linters/SAST tools

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@web/AGENTS.md`:
- Line 19: Update the import guidance to include cleanup: instruct developers to
import cleanup from "`@testing-library/react`" alongside render / renderHook / act
(e.g., import { render, renderHook, act, cleanup } from
"`@testing-library/react`") and remind them to call cleanup in an afterEach (e.g.,
afterEach(() => cleanup())) so tests with globals: false properly teardown DOM
between tests; reference the symbols render, renderHook, act, cleanup, and
afterEach in the guidance.
- Line 22: Rephrase the sentence that currently reads "it renders **zero virtual
rows**" to clearly state that jsdom provides no layout/measurement APIs so
unmocked virtualizers will render no rows (e.g., "jsdom provides no layout
measurements, so virtualizers typically render nothing unless mocked"); mention
the existing test workaround in TorrentTableOptimized.smoke.test.tsx which
deterministically renders all rows to exercise logic. Update AGENTS.md
accordingly so the intent and the test workaround are unambiguous.
- Around line 51-53: The three checklist items in AGENTS.md all start with the
verb "Add", making the openings repetitive; update one of the three bullets (the
lines that list adding namespace JSON files, updating
supportedLanguages/languageNames, and adapting the locale coverage script) to
use a different opening verb or phrasing (e.g., "Place", "Update", "Adapt", or
rephrase as "Include X in Y") so the list keeps parallel structure but avoids
identical sentence starts while preserving the original meaning.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 9fda70ee-7fab-429f-998b-958f358ddd22

📥 Commits

Reviewing files that changed from the base of the PR and between 53aef3e and 8d0568b.

📒 Files selected for processing (2)

• CONTRIBUTING.md
• web/AGENTS.md

✅ Files skipped from review due to trivial changes (1)

• CONTRIBUTING.md