Skip to content

docs: Fastify example is no-test — server.listen() blocks, harness only checks compile #147

@proggeramlug

Description

@proggeramlug

Summary

docs/src/stdlib/http.md advertises Fastify as "API-compatible with the npm package", but the example block is marked no-test because server.listen() blocks forever. The doc-tests harness therefore only verifies the example compiles and links — it never actually runs the server, makes a request, or confirms a response.

This means the "API-compatible" claim has no end-to-end test coverage in-repo for the one stdlib module people are most likely to try. Stubs or regressions in any handler / routing / reply path could land without the harness noticing.

Evidence

  • Example block in docs/src/stdlib/http.md tagged typescript,no-test with app.listen({ port: 3000 }, ...).
  • No matching integration test in test-files/ or crates/perry-stdlib/tests/ that starts a Fastify server and issues an HTTP request against it.

Suggested fix

Add a real integration test — either in test-files/ or as a doc-example test — that:

  1. Spawns the Fastify server in a background thread (or spawn_for_promise_deferred).
  2. Hits it with fetch from the main thread.
  3. Asserts the JSON response body.
  4. Shuts the server down cleanly.

Alternatively, expose a server.listen({ port, signal }) shape that takes an AbortController-style cancel so the doc example can exit deterministically, then flip the block off no-test.

Until one of those lands, the stdlib docs should probably qualify "API-compatible" → "partially implemented; see open issues" in the http page.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions