Integration Tests

Relevant source files

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

• test/integration/app.test.ts
• test/integration/versions/index.test.ts
• test/app/index.test.ts
• test/services/versions/v1/index.test.ts
• test/services/versions/v1/middleware.test.ts
• AGENTS.md

Integration tests in the FOSSBilling API project ensure that various modules—such as the Versions Service, Central Alerts, and Stats Service—work harmoniously with the Hono application router and platform bindings. These tests validate the full request/response cycle, including routing, middleware execution, cache persistence, and external API mocking.

The suite is built using Vitest and specifically targets the Cloudflare Workers environment pool. It verifies that environment bindings (KV namespaces and D1 databases) are correctly injected through middleware and accessible to service logic.

Sources: AGENTS.md:27-31, test/integration/app.test.ts:33-40

Testing Architecture

The integration testing strategy focuses on "Full App Integration," where the actual src/app/index.ts entrypoint is invoked using app.request(). This approach ensures that the entire stack, from route definition to final JSON serialization, is exercised.

Infrastructure Mocking

Since the API runs on Cloudflare Workers, tests utilize cloudflare:test utilities to simulate the runtime. This includes:

• ExecutionContext: Managed via createExecutionContext() and waitOnExecutionContext() to handle asynchronous tasks like background caching.
• KV Namespaces: CACHE_KV (for GitHub data) and AUTH_KV (for update tokens) are cleared and prepopulated before each test.
• D1 Database: Mocked implementations (e.g., mockD1Database) are bound to the environment to test data-driven services like Central Alerts.

Sources: test/integration/app.test.ts:41-55, test/app/index.test.ts:85-115

Request Lifecycle Flow

The following diagram illustrates the sequence of a typical integration test request:

The flow demonstrates how middleware bridges the gap between raw environment bindings and service-level logic.
Sources: test/integration/app.test.ts:133-150, test/app/index.test.ts:140-160

Core Test Scenarios

Service Discovery and Routing

Integration tests verify that the Hono router correctly delegates requests to the appropriate sub-services.

Endpoint Path	Target Service	Expected Result
/	Root Handler	200 OK with API Metadata
/versions/v1	Versions Service	200 OK with Release List
/central-alerts/v1/list	Alerts Service	200 OK with Active Alerts
/stats/v1/data	Stats Service	200 OK with Chart Data
/unknown/path	N/A	404 Not Found

Sources: test/integration/app.test.ts:58-95, test/app/index.test.ts:117-158

Cache Persistence and Recovery

A critical component of the API is the caching of GitHub API responses. Integration tests validate that data persisted in CACHE_KV by one request is successfully retrieved by subsequent requests, even if the external GitHub API fails (Stale-While-Revalidate pattern).

Authentication and Security

The /versions/v1/update endpoint requires Bearer authentication. Tests verify:

• Token Retrieval: Ensuring the UPDATE_TOKEN is correctly fetched from AUTH_KV.
• Unauthorized Access: Requests without a header or with an invalid token return 401 Unauthorized.
• Middleware Consistency: CORS headers are applied even on failed authentication attempts.

Sources: test/integration/app.test.ts:182-192, test/services/versions/v1/middleware.test.ts:200-230

Global Middleware Validation

Integration tests ensure that standard HTTP behaviors are consistently applied across all services via global middleware.

CORS and Headers

Every response must include Access-Control-Allow-Origin: *. Additionally, cacheable endpoints are checked for ETag generation to support If-None-Match conditional requests.
Sources: test/integration/app.test.ts:233-255, test/services/versions/v1/middleware.test.ts:113-145

Trailing Slash Handling

The application uses middleware to maintain URL canonicalization. Tests confirm that paths ending in a trailing slash (e.g., /versions/v1/) result in a 301 Moved Permanently redirect to the non-trailing version.
Sources: test/services/versions/v1/middleware.test.ts:86-111

Execution Commands

The project defines specific scripts in package.json to run the integration suite in different environments:

Command	Description
npm run test	Runs the default Vitest suite in the Workers pool.
npm run test:node	Runs tests using the Node adapter configuration.
npm run test:all	Executes both Worker and Node integration tests.
npm run test:coverage	Generates a coverage report for the integration suite.

Sources: package.json:7-13, AGENTS.md:20-25

Summary

Integration tests in the FOSSBilling API provide a safety net for the application's complex routing and caching logic. By mocking external dependencies while utilizing the actual Hono application instance, the suite ensures that environment bindings are correctly handled and that the API maintains a consistent contract across its various services.