Testing & Quality Assurance
Relevant source files
The following files were used as context for generating this wiki page:
Testing and Quality Assurance (QA) in Farm.js ensures that the framework maintains high performance, type safety, and production reliability across multiple renderers and deployment targets. The project uses a multi-layered verification strategy that spans unit tests for core logic, integration tests for full-stack boundaries, and end-to-end (E2E) browser testing for production-ready outputs.
Sources: AGENTS.md:1-20, ARCHITECTURE.md:100-120
Testing Strategy and Architecture
The Farm.js testing architecture prioritizes fast feedback during development and rigorous verification of production artifacts. Verification starts with the smallest possible test to disprove a change and broadens based on risk.
Verification Layers
The framework uses three primary testing layers to validate behavior:
- Unit Tests: Focus on utility functions, route parsing, matching logic, and individual core components.
- Integration Tests: Validate the route discovery process, the server rendering pipeline (SSR), and client-side hydration.
- Manual & E2E Testing: Utilize a "playground" application and examples to verify browser compatibility and real-world usage.
Sources: ARCHITECTURE.md:122-138, AGENTS.md:344-348
The diagram shows the progression from granular unit tests to broad E2E verification to ensure production safety.
Tooling and Commands
Farm.js employs Vitest for unit and integration testing and Playwright for cross-package browser coverage.
Key Test Commands
| Command | Scope | Purpose |
|---|---|---|
pnpm --filter @farm.js/core test | Core Framework | Tests configuration, routing, and shared logic. |
pnpm test:renderers | Renderers | Verifies React, Preact, Solid, Vue, and Svelte adapters. |
pnpm docs:check-navigation | Documentation | Validates docs route generation and internal links. |
pnpm test:e2e:framework | E2E | Runs Playwright tests against production builds. |
pnpm run test:compat | React Compatibility | Checks React 18/19 compatibility and runtime size. |
Sources: AGENTS.md:349-360, CONTRIBUTING.md:40-60
End-to-End (E2E) Verification
E2E tests ensure that production output functions correctly across different environments, including Vercel and standalone Nitro servers.
Production Routing and RSC
E2E tests verify that production API routes retain validation and global middleware. These tests ensure that SPA navigation correctly synchronizes document metadata and that client components hydrate successfully in production bundles.
The sequence diagram illustrates how Playwright verifies both UI hydration and backend API integrity in a production environment.
Documentation Site Verification
E2E testing specifically targets the documentation site to ensure:
- Navigation survives client-side transitions without full page reloads.
- Code blocks correctly copy source text to the clipboard, even under strict Content Security Policy (CSP) settings.
- Artwork and animations respect user "reduced motion" preferences.
- Markdown mirrors (.md versions of pages) are correctly served for LLMs and agents.
Sources: tests/e2e-production-sites/docs.production.spec.ts:15-100, packages/farm/src/tests/docs-navigation-runtime.test.ts:10-50
Integration and Core Logic Testing
Integration tests utilize Vitest to mock Node.js and browser environments for framework-specific features.
Content Loading and LLM Support
The framework tests its llms.txt and AGENTS.md generation to ensure that agents can discover and process site content accurately.
- llms.txt: Tests verify the serialization of structured data into Markdown according to the
llmstxt.orgspecification. - Content Loader: Tests in
packages/farm-contentensure that Markdown, MDX, and JSON files are loaded with stable IDs and that assets are correctly transformed into emitted URL imports.
Sources: packages/farm/src/tests/llms-txt.test.ts:15-80, packages/farm-content/src/loader.test.ts:30-100
Document Composition
Tests for full-document.ts ensure the framework can correctly detect and manipulate full HTML documents, merging Farm-managed assets like script tags and stylesheets into the correct <head> and <body> locations.
Sources: packages/farm/src/tests/full-document.test.ts:10-40
Quality Guidelines for Contributors
Farm.js maintainers follow a specific "Maintainer Taste" that guides testing practices:
- Regression Tests: Every bug fix must include a regression test that fails without the fix and passes with it.
- Deterministic Readiness: Developers must never replace a deterministic readiness signal (like a promise or event) with an arbitrary sleep.
- Platform Coverage: Tests must cover both Linux and Windows, as filesystem and path handling often diverge between these platforms.
- Safety: Core contracts must remain authoritative. Any optimizer must prove its eligibility before mutating the DOM to avoid breaking hydration or state.
Sources: AGENTS.md:60-80, AGENTS.md:362-368
Summary
The Testing & Quality Assurance system in Farm.js is a comprehensive suite designed to protect the framework's "Product Contract." By combining fast unit tests with robust E2E production site verification, the project ensures that features work not only in the Vite development environment but also in safe, optimized production outputs across various targets and renderers.