docs(frontend): add testing guide and refresh README#5170
Merged
Yicong-Huang merged 12 commits intoMay 24, 2026
Conversation
Three files at frontend/ root: - AGENTS.md scoped, auto-loaded agent rules: Vitest stack, three golden rules, minimum-viable spec template, anti-patterns red list, jsdom-vs-browser-mode decision. - TESTING.md canonical human-readable guide: stack overview, why detectChanges() drives template coverage, recipes, standalone-component patterns, mocking, anti-patterns, coverage troubleshooting, and a Karma to Vitest migration cheatsheet. - README.md replaces the stale ng-new stub; points testing-related questions to TESTING.md and AGENTS.md. Closes apache#5169
github-actions
Bot
added
frontend
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #5170 +/- ##
============================================
+ Coverage 43.43% 43.65% +0.21%
Complexity 2216 2216
============================================
Files 1049 1049
Lines 40575 40580 +5
Branches 4321 4324 +3
============================================
+ Hits 17625 17715 +90
+ Misses 21855 21766 -89
- Partials 1095 1099 +4
*This pull request uses carry forward flags. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Two changes across all three frontend docs: - Single-line paragraphs and list items so GitHub renders consistent flowing prose; intra-paragraph hard wraps removed. - Scoped down to the current stack: drop migration-cheatsheet section and spy-rewriting anti-pattern. The remaining content describes Vitest patterns directly without contrasting against a previous setup.
Specific Angular / Vitest / Node / Yarn version numbers rot quickly and disagree with whatever is actually pinned in `package.json` and `engines`. Replace them with version-free framework names. Readers who need the exact version look at `package.json`.
…humans and agents The previous wording positioned TESTING.md as the human-facing counterpart to AGENTS.md. In practice both audiences read it: humans during onboarding and PR review, agents on demand whenever AGENTS.md's rules need a deeper recipe or troubleshooting context. Update the opening lines of AGENTS.md / TESTING.md and the README pointer to say so explicitly.
aglinxinyuan
approved these changes
May 23, 2026
Contributor
There was a problem hiding this comment.
Pull request overview
Adds and refreshes frontend-facing documentation to capture the current Angular + Vitest testing stack/conventions and replace the stale Angular CLI stub README for contributors working in frontend/.
Changes:
- Add
frontend/TESTING.mdas the canonical frontend unit-testing guide (Vitest stack, recipes, jsdom vs browser-mode decision, coverage troubleshooting). - Add
frontend/AGENTS.mdas scoped, auto-loading AI agent rules for thefrontend/subtree, pointing toTESTING.mdfor depth. - Refresh
frontend/README.mdwith project-specific setup/commands/layout and links to the new docs.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| frontend/TESTING.md | New canonical testing guide describing the current Vitest/jsdom + Playwright browser-mode setup and common testing recipes. |
| frontend/AGENTS.md | New scoped agent instructions for frontend work, summarizing rules and pointing to TESTING.md. |
| frontend/README.md | Replaces Angular CLI stub with Texera UI-specific commands, layout, and doc pointers. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…ointers AGENTS.md was duplicating most of TESTING.md (minimum-viable spec template, anti-pattern table, browser-mode decision). That content belongs in TESTING.md once and is reached on demand. Trim the testing section to the three rules an agent should keep in working memory plus a hard pointer to TESTING.md. In exchange, add the content that actually belongs in a scoped agent context for `frontend/`: - a layout table framed as "if you're touching X, look in Y", including the generated and vendored files that should never be hand-edited; - placement rules (features colocate their components/services/types, Stub…Service siblings live next to the real service); - expanded pointers — repo-wide testing philosophy, PR conventions, architecture map, coverage dashboard, browser-mode rationale PR.
Treat README.md as the source of truth for the stack, prerequisites, commands, project layout, and the basic doc pointers — those render on the GitHub folder page and are read by every human visitor. AGENTS.md now carries only what README does not: placement rules for new files (including the "do not hand-edit" codegen / vendored list), agent-relevant conventions (standalone, formatter, stub reuse), the testing checklist that fronts TESTING.md, and pointers that go deeper than the README's surface entries (named ../AGENTS.md sections, the coverage dashboard, and the browser-mode setup PR).
…NG.md only Two pointers do the job: the testing reference itself and the repo-wide testing philosophy. Drop the AGENTS.md / CONTRIBUTING.md / parent AGENTS.md bullets — the first auto-loads for agents, the others are one folder up and surface through the root docs.
…ad next" A `## Testing` section between Common commands and Project layout is the natural home for the TDD pointer and the link to TESTING.md. Restore the original "Where to read next" bullets for AGENTS.md, the repo-wide CONTRIBUTING.md, and the repo-wide AGENTS.md.
The Testing section now carries the only outbound pointers that really belong in a frontend quickstart. AGENTS.md auto-loads for agents; ../CONTRIBUTING.md and ../AGENTS.md surface naturally one folder up. Also update AGENTS.md's stale references to the dropped section.
…section "Tests come first" is the TL;DR; readers who want the workflow follow TESTING.md from here, which already links the repo-wide guidance.
The line cited specific line counts and a coverage percentage that will drift as the spec evolves. Other recipes already point at the same file from a stable angle.
Prettier wants a blank line between the closing code fence and the next subsection heading; the previous edit removed the surrounding context together with the deleted line.
This was referenced May 24, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changes were proposed in this PR?
Three docs at the root of
frontend/:README.md— replaces the default Angular-CLI stub. Quickstart with stack, setup, common commands, a short Testing section, and the project layout.TESTING.md— canonical testing reference for humans and agents. Stack, thefixture.detectChanges()mental model, recipes, jsdom-vs-browser-mode decision, anti-patterns, and coverage troubleshooting.AGENTS.md— scoped agent rules. Placement rules for new files, frontend conventions, the testing checklist that frontsTESTING.md, and deeper pointers.The three are deduplicated: README is the source of truth for stack / commands / layout; AGENTS.md points back to it; TESTING.md holds the testing depth.
Any related issues, documentation, discussions?
Closes #5169. Captures the conventions in use today (
async () =>inbeforeEach, standalone components inimports:,vi.fn()mocks, the two-target jsdom / browser-mode split from #5017).How was this PR tested?
Documentation-only.
prettier --checkpasses on all three files. Inline code samples come from existing specs (mini-map.component.spec.ts,workspace.component.spec.ts,workflow-editor.component.spec.ts); the helpers and configs they reference all exist onmain.Was this PR authored or co-authored using generative AI tooling?
Generated-by: Claude Opus 4.7