Testing Strategy & QA Tooling

Relevant source files

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

• CLAUDE.md
• backend/lib/tests/openrouter.test.ts
• extension/src/content/tests/pdf-page-summaries.test.ts
• packages/shared/src/tests/exports.test.ts
• README.md
• CHANGELOG.md

The Oddity 1 project employs a multi-layered testing strategy that combines automated unit testing, integration testing, and a rigorous workflow for manual verification. The strategy ensures that core AI annotation engines, PDF processing logic, and shared TypeScript contracts maintain high integrity across the backend and Chrome extension workspaces.

Sources: README.md:126-130, CLAUDE.md:27-33

Automated Testing Suites

The project uses Vitest as the primary test runner across the monorepo. Tests are organized within __tests__ directories located near the source code they validate.

Core Testing Pillars

Layer	Tooling	Focus Area
Static Analysis	TypeScript & ESLint	Type safety and code quality standards.
Unit Testing	Vitest	Validation of LLM clients, utility functions, and shared constants.
Integration Testing	Vitest + JSDOM	DOM-based testing for PDF summarization and extension content scripts.
Schema Validation	Custom Validators	Ensuring API responses and shared objects match expected structures.

Sources: README.md:126-130, tasks/todo.md:104-108

Shared Contract Testing

Tests in packages/shared/src/__tests__/exports.test.ts verify that the core communication contracts between the backend and extension remain stable. This includes timing constants, feature flags for subscription tiers (Free vs. Standard), and annotation color mappings.

Sources: packages/shared/src/tests/exports.test.ts:7-45

Backend & LLM Testing

The backend testing strategy focuses on the reliability of AI interactions. The openrouter.test.ts suite mocks network requests to simulate complex LLM behaviors, including Server-Sent Events (SSE) streaming and error recovery.

LLM Streaming and Fallbacks

The system tests three primary scenarios for AI generation:

1. Successful Streaming: Validates that chunks are parsed and returned in real-time.
2. Stream-to-Buffered Fallback: If a streaming parse error occurs, the system attempts to fall back to a standard JSON response to prevent failure.
3. Key Rotation: Tests the rotation to backup API keys upon receiving rate limit (HTTP 429) errors from OpenRouter.

Sources: backend/lib/tests/openrouter.test.ts:114-142, backend/lib/tests/openrouter.test.ts:184-211

The diagram shows the logic for handling LLM streaming failures and key rotation during annotation generation.

Extension & Content Script Testing

Extension testing utilizes JSDOM to simulate the browser environment. Tests in extension/src/content/__tests__/pdf-page-summaries.test.ts focus on the transformation of PDF documents into annotatable HTML.

PDF Summarization Logic

The test suite validates the lifecycle of PDF summaries:

• DOM Normalization: Converting flat PDF-to-HTML output into structured #page-container elements.
• Hashing: Computing unique document hashes based on concatenated page text to manage caching.
• UI Mounting: Verifying that Floating Action Buttons (FAB) and modal backdrops mount directly to the document.body to avoid layout corruption in the converted PDF.

Sources: extension/src/content/tests/pdf-page-summaries.test.ts:98-135, extension/src/content/tests/pdf-page-summaries.test.ts:167-185

User Interaction Testing

Tests simulate user events like clicking the "Summarize" button, verifying that buttons are disabled during active generation and that text is correctly copied to the clipboard via the navigator.clipboard API.

Sources: extension/src/content/tests/pdf-page-summaries.test.ts:241-267, extension/src/content/tests/pdf-page-summaries.test.ts:316-324

QA Workflow and Orchestration

The project enforces a "Plan First" workflow to minimize architectural debt and ensure verification is integrated into the development process.

Plan and Verification Mode

For any non-trivial task, the workflow requires:

1. Entry into Plan Mode: Writing detailed specifications in tasks/todo.md before implementation.
2. Verification Steps: Tasks are not marked complete until the behavior is proven through tests or log checks.
3. Self-Improvement Loop: After any correction, the developer must update tasks/lessons.md to prevent recurring mistakes.

Sources: CLAUDE.md:3-33, tasks/todo.md:70-84

The diagram represents the iterative workflow from planning to final verification enforced in the project.

Manual Validation Checklist

Before deployment, a 14-point validation checklist must be satisfied, covering:

• Extension loading and manifest MV3 structure.
• Auth flows (Signup/Login).
• Site-specific adapters (ChatGPT, Claude, Medium).
• UI components (Shadow DOM popovers, manual annotations).
• Performance features (Lazy loading, caching).

Sources: tasks/todo.md:35-50, CHANGELOG.md:129-145

Conclusion

The Oddity 1 testing strategy prioritizes resilience in AI operations and DOM stability in the Chrome extension. By combining Vitest for automated logic verification with a structured "Plan First" manual QA workflow, the project ensures that complex features like PDF export and real-time streaming annotations function reliably across diverse web environments.