Test Mocks & Helpers

The FOSSBilling API project utilizes a comprehensive suite of test mocks and utility helpers to simulate external dependencies and platform-specific behaviors. These tools enable the execution of unit and integration tests without requiring a live Cloudflare infrastructure, real GitHub API connectivity, or persistent database storage.

The testing architecture is designed to mirror the source layout, with shared utilities located in test/utils/ and specialized mock data or adapter implementations in test/mocks/. This approach ensures that feature logic remains runtime-agnostic and testable across different environments, such as the Vitest pool for Workers or Node.js.
Sources: AGENTS.md:1-25, test/mocks/README.md:1-12

Core Mock Components

The project relies on specific mock structures to replicate the Cloudflare Workers environment and external API responses.

Platform and Storage Mocks

To test services that interact with Cloudflare-specific bindings like D1 (SQL database) and KV (Key-Value storage), the project uses mock adapters. These simulate the behavior of the CloudflareBindings interface.

The D1 mock implementation includes logic for preparing statements, binding parameters, and returning structured results that match the expected D1Result format.
Sources: test/mocks/README.md:5-10, test/services/extensions/v1/index.test.ts:110-175, test/utils/test-types.ts:153-176

GitHub API Mocking

Since the API service acts as a hub for versioning data, it heavily mocks the GitHub Octokit library. This includes mocking both REST requests (@octokit/request) and GraphQL queries (@octokit/graphql).

Sources: test/utils/mock-helpers.ts:3-56, test/utils/test-types.ts:135-151

Mock Data Structures

The project maintains static datasets to ensure consistent test results across various service modules.

GitHub Release Data

Static release information is used to test the Versions and Stats services. This data includes semantic version tags, publishing dates, and asset metadata.

Extension and Composer Data

To test the Extensions API and PHP version requirement logic, the project uses mock composer.json objects and extension database rows.

• Composer Mocks: Define PHP requirements (e.g., ^8.1).
• Extension Mocks: Define attributes like author_id, releases (JSON string), and download_url.
  Sources: test/mocks/github-releases.ts:75-87, test/services/extensions/v1/index.test.ts:17-108

Implementation Details

Synthetic GraphQL Responses

The createGraphQLImplementation helper is particularly significant. It parses the incoming GraphQL query for aliases and dynamically builds a response object. This allows the test suite to simulate scenarios where composer.json is missing or contains malformed JSON without needing a real GitHub endpoint.

export function createGraphQLImplementation(
  composerJson: Record<string, unknown> | null,
  rawBlobText?: string
) {
  return async (query: string) => {
    const repoData: Record<string, { text: string } | null> = {};
    for (const [, alias] of query.matchAll(/(\w+): object\(expression:/g)) {
      if (rawBlobText !== undefined) {
        repoData[alias] = { text: rawBlobText };
      } else {
        repoData[alias] = composerJson
          ? { text: JSON.stringify(composerJson) }
          : null;
      }
    }
    return { repository: repoData };
  };
}

Sources: test/utils/mock-helpers.ts:33-51

Mocking D1 Database Operations

The D1 mock found in the extension tests demonstrates a sophisticated way to simulate SQL operations. It tracks bound parameters and filters an in-memory array (testExtensions) based on the query string (e.g., filtering by extension type or performing case-insensitive lookups by id).
Sources: test/services/extensions/v1/index.test.ts:110-165

Conclusion

The Test Mocks & Helpers in the FOSSBilling API project provide a robust foundation for platform-independent testing. By abstracting away the complexities of Cloudflare Workers and the GitHub API, developers can ensure that service logic is correct and handles edge cases—such as API timeouts, missing files, or cache corruption—reliably before deployment.