Website and Playwright Tests

Relevant source files

The following files were used as context for generating this wiki page:

• test/browser/playwright.config.js
• test/browser/site.spec.js
• test/site_test.js
• rake/site_build.rb
• rake/site_docs.rb
• test/site_links.py
• rake/docs_contract.rb
• AGENTS.md

The Mutineer website serves as the primary documentation hub, featuring guides for AI agents, Rails integration, and JSON report schemas. The project employs a multi-layered testing strategy to ensure documentation accuracy, link integrity, and interactive feature functionality across different browsers and themes.

The testing suite validates that the built site—generated as a collection of HTML and Markdown files—maintains a stable contract with users and automated agents. It covers everything from low-level link checking to high-level browser interactions like theme switching and video playback.

Sources: rake/site_docs.rb, AGENTS.md:43-52, test/browser/site.spec.js

Site Architecture and Build Process

The website is a static site published to GitHub Pages from the _site/ directory. The build process assembles hand-written documentation, generated API references, and specialized files for LLM ingestion.

Build Components

The build process is managed by SiteBuild and involves several stages:

1. Cleanup: Removes the existing _site directory to ensure a clean state.
2. Tree Copying: Copies tracked files from docs/ to the destination.
3. API Generation: Uses YARD to generate HTML documentation for the Ruby API.
4. Content Splicing: Injects the "Production Ready" section from the README.md into index.html and index.md.
5. Artifact Generation: Creates llms-full.txt, json-schema.html, and sitemap.xml.

Sources: rake/site_build.rb:14-43, rake/site_docs.rb:11-37

Site Catalog and Navigation

The site maintains a central catalog of entries that defines the structure and priorities for the sitemap and llms.txt index.

Path	Section	Title	Description
/	:docs	Overview	Operators, install, and CLI flags.
/agentic-coding.html	:docs	AI Agents & CI	Agent loop and regression gating.
/rails.html	:docs	Rails rollout	Guides for Rails integration.
/json-schema.html	:docs	JSON report schema	Versioned JSON contract reference.
/api/	:docs	Ruby API (YARD)	Class reference generated from code.

Sources: rake/site_docs.rb:16-37

Testing Frameworks and Strategy

The project utilizes three distinct testing layers for the website: Python for link validation, Node.js for unit testing client-side logic, and Playwright for end-to-end browser testing.

Link Validation (Python)

The test/site_links.py script parses built HTML files to verify:

• Internal Links: Ensures all local href and src attributes point to existing files within the site tree.
• Fragments: Validates that internal anchors (e.g., #section-name) exist in the target file.
• README Anchors: Checks links pointing to the project README.md on GitHub against actual Markdown headings.
• Unique IDs: Prevents duplicate HTML id attributes within a single page.

Sources: test/site_links.py:1-85

Client-Side Logic (Node.js Unit Tests)

The test/site_test.js suite uses the Node.js vm module to test docs/assets/mutineer.js in a simulated browser environment. It mocks DOM objects like document, window, and IntersectionObserver to validate:

• Video Autoplay: The explainer video plays when in view and pauses when hidden or in a background tab.
• Theme Selection: The site respects the system theme but allows manual overrides, even if localStorage is blocked.
• Clipboard Interaction: The "Copy" buttons provide visual feedback and handle concurrent clicks or permission denials.

Sources: test/site_test.js:80-165

Browser Testing (Playwright)

Playwright provides end-to-end validation across multiple browser engines. These tests ensure that the visual and interactive elements function correctly on real devices.

The diagram above shows the flow of end-to-end website testing within the CI pipeline.
Sources: test/browser/site.spec.js, AGENTS.md:46-52

Documentation Contract and LLM Integration

The project enforces a "Documentation Contract" to ensure technical details remain consistent across various surfaces, including the website, README, and AI agent guides.

Contract Synchronization

The DocsContract module acts as a single source of truth for:

• Exit Codes: Shared between README.md, STABILITY.md, and the website.
• JSON Schema: Automatically renders json-schema.html from the Markdown source.
• Action Descriptions: Slices text into action.yml so GitHub Action inputs match the documentation.

Sources: rake/docs_contract.rb:7-110

AI Agent Support

To support AI coding agents, the build process generates specialized text files that concatenate documentation for easy ingestion.

File	Purpose
llms.txt	A prioritized index of documentation URLs for agents.
llms-full.txt	A single file containing the README, Agent/CI guide, and JSON schema.
skill.md	A compact "skill card" for agent installation and usage loops.

Sources: rake/site_docs.rb:83-93, rake/docs_contract.rb:64-88, rake/site_build.rb:63-65

Interaction and Accessibility Features

The testing suite places significant emphasis on accessibility and user experience under different conditions.

Theme and Motion Logic

Tests verify that the site correctly handles CSS color-scheme and prefers-reduced-motion media queries. If a user enables "Reduced Motion" mid-visit, the site must immediately finish any running animations and hide progress indicators.

JavaScript Fallback

Playwright tests specifically check the site with JavaScript disabled. In this mode:

• The "Theme" toggle is hidden.
• The "Copy" buttons are hidden.
• Content remains readable and layout remains stable.
• The <details> blocks (like the "boundary test") remain interactive via native HTML behavior.

Sources: test/browser/site.spec.js:1-55, test/site_test.js:141-175

Conclusion

Website and Playwright tests ensure that Mutineer's documentation remains as reliable as the code it describes. By combining static link analysis, simulated environment unit tests, and full browser automation, the project maintains a high-quality documentation site that serves both human developers and AI agents effectively.