Testing Strategy & Frameworks

Relevant source files

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

• README.md
• AGENT_4_DEVOPS_DOCS.md
• CLAUDE.md
• SWEEPBOT_DASHBOARD.html
• CODEBASE_IMPROVEMENTS.md
• PR_CODE_REVIEW_FIXES.md

Introduction

The testing strategy for SweepBot is designed to ensure the reliability and security of its core modules, particularly the NLP flow engine and financial transaction tracking. The project utilizes a monorepo approach with standardized testing tools across the API, web dashboard, and browser extension. The primary objective is to maintain high code quality (targeting >80% coverage) while preventing regressions in critical paths such as authentication, session tracking, and billing.

The testing architecture is categorized into unit, integration, and End-to-End (E2E) layers. The packages/flows module represents the most mature testing implementation in the project, featuring a production-ready suite with over 285 assertions.

Sources: README.md, CLAUDE.md, AGENT_4_DEVOPS_DOCS.md

Core Testing Frameworks

SweepBot employs a modern JavaScript/TypeScript testing stack. The project has standardized on Vitest for unit and integration testing due to its speed and compatibility with the Vite-based frontend.

Primary Tools and Libraries

Tool	Scope	Description
Vitest	Unit / Integration	Primary test runner for apps and packages. Used for testing logic in the API and Flows engine.
Playwright / Puppeteer	E2E	Used for browser-based automation and verifying critical user journeys in the web app.
Testing Library	Frontend	Includes @testing-library/react and jest-dom for testing React components in apps/web.
Fastify Inject	API	Utilized in apps/api to simulate HTTP requests without a live server listener.

Sources: README.md, CLAUDE.md, CODEBASE_IMPROVEMENTS.md

Test Architecture and Data Flow

The testing pipeline is integrated into the CI/CD workflow, managed by the DevOps/QA specialist (Agent 4). Tests are executed in isolated environments with mocked external services like Supabase and Redis to ensure determinism.

This diagram illustrates the hierarchical testing structure where unit tests feed into integration and E2E layers. Sources: AGENT_4_DEVOPS_DOCS.md, CLAUDE.md, CODEBASE_IMPROVEMENTS.md

Specialized Testing Modules

NLP Flow Engine (packages/flows)

The Flow Engine is the most heavily tested component. Its suite covers the entire pipeline from natural language interpretation to execution.

• EntityRecognizer Tests: Verifies extraction of platforms, games, and amounts.
• FlowInterpreter Tests: Validates the 4-pass pipeline (entities → intent → AST → validation).
• Responsible Play Validation: Non-negotiable tests for max_duration and cool_down_check guardrails.
• Coverage Status: 54 test suites with 285+ assertions.

Sources: README.md, AGENT_COORDINATION.md, CLAUDE.md

API and Backend Testing

API testing focuses on the lifecycle of a user session and transaction batching.

• Mocking Strategy: External calls to Supabase and Stripe are intercepted and mocked using Vitest's vi.mock.
• Critical Path Suites:
  1. Auth: Verifies JWT bearer token verification and requireAuth hooks.
  2. Sessions: Tests for session creation, ending, and batch transaction inserts (up to 500 tx).
  3. Billing: Mocks Stripe webhooks and verifies subscription tier updates.

Sources: SWEEPBOT_DASHBOARD.html, CODEBASE_IMPROVEMENTS.md

Testing Operations and Commands

Tests can be run at the root level or within specific app/package directories. Turborepo handles dependency ordering to ensure packages are built before they are tested.

CLI Commands

Command	Result
pnpm test	Executes all Vitest test suites across the monorepo.
pnpm test:watch	Enters watch mode, frequently used during development of the flows package.
pnpm test:coverage	Generates a coverage report; the project goal is 80%+.
pnpm --filter @sweepbot/web test:e2e	Runs Playwright/Puppeteer E2E tests for the frontend.

Sources: CLAUDE.md, README.md

Quality Standards and Readiness

The project maintains strict "Launch Readiness" gates that require all tests to pass before merging into the protected main branch.

Current Implementation Gaps

While the Flow Engine is production-ready, other areas have identified gaps in their testing strategy:

• API Coverage: Historically low coverage identified in audits, requiring new suites for auth and billing.
• E2E Reliability: A priority for Phase 2 to ensure "Action Execution" via the browser extension works across different casino platforms.
• UI Testing: Integration of OnboardingTour tests was recently identified as a critical fix to prevent crashes in private browsing modes where localStorage is unavailable.

Sources: SWEEPBOT_DASHBOARD.html, PR_CODE_REVIEW_FIXES.md, AGENT_4_DEVOPS_DOCS.md

Summary

SweepBot's testing strategy balances rigorous unit testing for its core automation engine with simulated integration tests for its API. By utilizing Vitest across the monorepo and enforcing responsible play guardrails within the test logic, the framework ensures both technical stability and regulatory compliance. As the project moves into Phase 2, the focus is shifting toward expanding E2E coverage and resolving historical gaps in API and UI testing to meet the 80% coverage mandate.

Sources: README.md, CLAUDE.md, AGENT_4_DEVOPS_DOCS.md