Dynamic port assignment in Fastify v4: test isolation when reusing instances

Question

Goal
Use Fastify’s inject method to run credential‑free integration tests while relying on dynamic port assignment ({ port: 0 }) to avoid hard‑coded ports and port collisions.
Uncertainty
After a test calls fastify.listen({ port: 0 }) and later fastify.close(), it is not fully clear whether the internal server address, plugin decorators, and encapsulation boundaries are completely reset for a subsequent test that creates a new listener on the same Fastify instance, or whether a brand‑new Fastify instance is required to guarantee isolation.
Specifically, the interaction between the v4 listen promise‑based API, the automatic plugin encapsulation mechanism, and the OS‑selected ephemeral port raises questions about state leakage when the same instance is reused across test files or suites.

Does closing the listener fully clear the address binding and any request‑scoped decorators added by plugins?
If residual state remains, what additional reset steps are needed without instantiating a new Fastify object?
How does plugin encapsulation behave when a listener is reopened on the same instance versus when a fresh instance is created?

Tasadduq Burney · Answer

Direct answer
When a Fastify v4 instance calls listen({port:0}) and later close() the OS ephemeral port is released but plugin decorators and encapsulation boundaries are not automatically reset. Re-using the same instance for a new listen may retain prior test state risking isolation failures.
Likely explanation

listen({port:0}) binds an OS-assigned ephemeral port and returns the address object.
fastify.close() releases the port but does not automatically reset plugin decorators or encapsulation state.
Re-using the same Fastify instance for a new listen may retain request-scoped decorators and encapsulation boundaries from the prior test.

Confirmed facts
After fastify.close() fastify.server.address() returns null if the port is fully released. Plugin decorators added via fastify.decorate() or plugin-scoped hooks persist across re-calls to listen() on the same instance unless explicitly cleared.
Steps needed for this case

After fastify.close() run console.log(fastify.server.address()) to verify the port is null.
If decorators must be reset explicitly re-decorate or create a new Fastify() instance for the next test.
Run a minimal fastify.inject({method:'GET',url:'/'}) after a fresh listen to confirm decorators and encapsulation behave as expected.

Missing diagnostic detail
Does the test suite explicitly clear plugin-added request headers or auth context between runs? Confirming this will determine whether a full instance reset or targeted cleanup is the recommended approach.

Dynamic port assignment in Fastify v4: test isolation when reusing instances

Goal

Uncertainty

1 answer

Direct answer

Likely explanation

Confirmed facts

Steps needed for this case

Missing diagnostic detail

Your perspective belongs here.

0 question comments