test(agent-bff): drive a generated client through list, count, form and execute

[nbouliol]

What

Proves the dynamic OpenAPI document is correct enough for codegen, not just schema-valid: a client generated from it can actually call list, count, action form and action execute.

The test:

1. emits the document through the CLI command (dispatchCli(['openapi', '--output', …]), the body of forest-bff openapi) from a fixture schema and fixture capabilities;
2. runs @hey-api/openapi-ts on that file, as a consumer would from the command line;
3. drives the generated client over HTTP against the real data and action middlewares (agent clients faked through the existing createClient seam), asserting a 2xx and the exact response body for each of the six operations.

One fixture feeds both the document and the runtime read-model. Two sources would let the test go green while the document described a surface the runtime does not have.

Why the operator check has teeth

The filter operator is read from the emitted enum (components.schemas.FilterLeaf_users-1.properties.operator.enum) and injected into the call, instead of being hardcoded — so the assertion follows the document rather than a human's memory of it.

A negative control sends an operator the document leaves out and asserts 400 invalid_filter_operator. Without it, a permissive stub (or a regression that stopped validating) would keep the check green. The fixture reports a single capability operator (equal → Equal) so the out-of-set operator lands unambiguously on 400 rather than on 422 field_not_filterable or 500 mapping_error.

What it found

Nothing broken. Worth recording, since these were the risks:

• the percent-encoded action segments survive codegen and the round trip, including a non-ASCII name (Générer la facture → G%C3%A9n%C3%A9rer%20la%20facture);
• the recursive anyOf filter tree becomes a clean recursive TS union, and the operator enum reaches the generated types as a string literal;
• not is dropped by the codegen — a tooling quirk, not a document defect: the union already encodes the leaf/branch exclusivity structurally, and the runtime 400 stays documented in prose. The document is unchanged.

Notes

• @hey-api/openapi-ts over openapi-generator-cli: the document is OpenAPI 3.1, and openapi-generator converts 3.1 → 3.0 internally, which would make "document defect vs tooling quirk" undecidable on exactly the constructs at risk. It also avoids a Java toolchain and a jar download inside a CI test.
• Auth stays out of scope, as the ticket states — but the generated client does send the documented X-Forest-Bff-Key scheme, and the test asserts the credential arrives under that header.
• The generated client lands in a gitignored test/openapi/.generated/, wiped before and after the run. ESLint ignores dot-directories by default, so no lint config change was needed.
• Runtime: the whole file takes ~2.5 s; the package suite stays at ~10 s (1093 tests green).

Fixes PRD-687

🤖 Generated with Claude Code

Note

Add generated-client test suite for agent-bff OpenAPI operations

• Adds a Jest test in openapi-generated-client.test.ts that runs the CLI to emit an OpenAPI doc, invokes @hey-api/openapi-ts to generate a TypeScript client, then drives the client against an in-memory Koa server through list, count, form, and execute flows.
• Verifies the generated client exports documented operationIds, propagates security and timezone headers, accepts documented filter operators (Equal), and rejects undocumented ones (GreaterThan) with a 400.
• Adds @hey-api/openapi-ts 0.99.0 to package.json and ignores the .generated output directory in .gitignore.

Changes since #1828 opened

• Added validation for OpenAPI client generation with action names containing path separators [1bf8e77]
• Modified the beforeAll hook in the OpenAPI generated client test to capture stderr before spy restoration and clear inherited Node options during codegen [1bf8e77]
• Moved the ignore rule for test/openapi/.generated from root .gitignore to packages/agent-bff/.gitignore [1bf8e77]

^{Macroscope summarized 90b37ef.}

[linear-code]

PRD-687

[qltysh]

Coverage Impact

This PR will not change total coverage.

🚦 See full report on Qlty Cloud »

🛟 Help

• Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

• Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

• File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

  • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.

[Tonours]

Second pass on the branch head. Five findings: one blocking (the emission-failure message is always empty), two tests that cannot fail, one latent coupling and one gitignore placement.

[Tonours]

All five findings are addressed. I verified the two decorative tests now bite, by mutation rather than by reading the diff:

• segment returning name unchanged: should reach an action whose name carries the path separator goes red (14 passed, 1 failed). The Facture 50/50 fixture is what gives it teeth.
• operator: { type: 'string', enum: operators } down to a bare { type: 'string' }: should carry the documented operator set into the generated types now goes red too, along with the two operator tests (12 passed, 3 failed). It stayed green before the literal assertion.

The other three read clean: written is captured before mockRestore(), NODE_OPTIONS: '' isolates the child's output from the runner's flags, and the ignore rule moved into packages/agent-bff/.gitignore with the root entry gone.

Package suite 1099/1099 green locally, CI green on 1bf8e77.