Overview

The Supertest harness (located in dapp/e2e/supertest) exercises the public-facing API routes using Vitest + Supertest. It currently ships three suites:

• api.test.ts — covers the token gate surfaces (/api/openapi, /api/token-status/:tokenId, /api/nonce, /api/gate-access, /api/form-submission-gate) with both happy/sad wallet scenarios and optional OpenAPI validation.
• jwt.test.ts — drills into JWT issuance/consumption, SIWE vs legacy branches, payload shape, and abuse cases.
• pinecone.test.ts — runs the MCP JSON-RPC bridge (/api/mcp) including tools/list, tools/call, JWT gating, and Pinecone vector searches.

Every suite imports the shared validateSupertestEnv helper (env.schema.ts) so test runs fail fast when required configuration is missing.

Environment & Configuration

Environment resolution is centralized in vitest.config.supertest.ts:

1. Start with process.env (CI/job variables win).
2. Overlay .env.supertest if it exists in dapp/.
3. Fall back to .env only when .env.supertest is absent.
4. Validate the merged object with supertestEnvSchema.

Key variables (see dapp/.env.supertest.example):

setup.ts logs the resolved values (with masked secrets) before the first test so you can confirm the harness picked up the right environment.

Running the suites

pnpm vitest --config dapp/e2e/supertest/vitest.config.supertest.ts

Tips:

• Tests intentionally sleep (waitForRateLimit) between cases to avoid backend throttles. Keep that helper intact if you extend the suite.
• The harness attempts to load public/openapi.json. If the file is missing in a given deployment, the OpenAPI validator quietly disables itself and tests continue.
• Output includes a summarized OpenAPI validation report plus JWT payload snippets to help debug server responses.

What each suite covers

api.test.ts

• OpenAPI surface — Fetches /api/openapi, asserts version 3.0.3, and (when available) validates the response against the generated schema via openapi-validator.ts.
• Token lifecycle — Runs describe.each happy/sad cases to hit /api/token-status/:tokenId (existing vs bogus token IDs) and /api/nonce (expects 200 with nonce when SIWE is enabled or 501 with RFC7807 payload otherwise).
• Gate access — Exercises /api/gate-access through SIWE or legacy envelopes depending on runtime config. Successful paths store any returned JWTs for reuse tests.
• JWT reuse edge cases — Sends valid/invalid/mismatched Bearer headers, tokenId body overrides, malformed headers, and concurrent requests to ensure the handler enforces strict matching.
• Form submission — Posts to /api/form-submission-gate with a properly signed legacy envelope, tolerating rate limits or backend 500s but asserting success/authorization codes otherwise.
• Global assertions — Waits between tests, prints structured logs, and emits the OpenAPI validation report in afterAll.

jwt.test.ts

• JWT minting — Verifies that a successful SIWE or legacy gate access call returns an accessToken when the server is configured to issue JWTs.
• Payload inspection — Uses jwtAssertions to check sub, tokenId, kind, scopes, timestamp claims, SIWE projection (siwe.*), and the deterministic siwe_hash.
• Authenticated reuse — Replays stored tokens against /api/gate-access with/without tokenId in the body, expecting success or precise failures (401 on mismatched IDs, 403 when already used).
• Bearer permutations — Validates lower/upper/missing space variants as well as outright malformed tokens, mock JWTs, and invalid formats defined in jwtScenarios.
• Rate limiting & uniqueness — Drives bursts of Bearer calls to detect 429s and confirms new authentications mint unique JWT IDs (jti) and timestamps.
• Introspection — Parses TTL to ensure it falls within the expected 5 minutes–24 hours window and logs helpful debug information when a server declines to issue tokens.

pinecone.test.ts

• Protocol guards — Ensures /api/mcp rejects GET (405), invalid JSON (400), and missing JWTs when NEXT_PUBLIC_AI_CHAT_REQUIRES_JWT is true.
• Tool discovery — Calls tools/list, asserts the response contains pinecone_search, and inspects the tool’s schema.
• Vector searches — Issues multiple tools/call requests covering default topK, custom topK, metadata toggles, invalid index/namespace, missing params, empty query strings, and concurrent invocations.
• JWT handling — Acquires a JWT up front (via SIWE or legacy gate access) when required, then reuses it for the MCP calls; also checks invalid tokens and malformed Bearer headers return 401s.
• Diagnostics — Logs the JWT payload (when present) plus Pinecone content to simplify debugging remote responses.

Coverage map

Extending the harness

• Share helpers via jwt.helpers.ts or new modules instead of duplicating logic inside a test file.
• Keep rate-limit sleeps configurable so suites remain reliable both locally and in CI.
• When you add a new endpoint to the tests, update this page (and the relevant API doc) so readers always know which specs are backed by automated coverage.
• If you introduce another OpenAPI slice, register its schema in openapi-validator.ts or extend the validator to support multiple specs.