Weave Code
Test Server Laravel Package
guzzlehttp/test-server
Guzzle Test Server is a dev-only testing helper that starts a local Node.js HTTP server, letting PHP tests queue responses and inspect received requests for handler and integration tests.
Node.js server and PHP controller
Frequently asked questions about Test Server
- How does guzzlehttp/test-server compare to Laravel’s Http::fake() for testing API clients?
- guzzlehttp/test-server provides a real HTTP server, unlike Http::fake(), which mocks Laravel’s HTTP layer. Use it for testing third-party API clients, auth flows, or middleware where realistic HTTP behavior (headers, redirects, WebSockets) is critical. Http::fake() is simpler for basic Laravel HTTP interactions.
- Can I use this package in Laravel’s PestPHP or PHPUnit tests?
- Yes, it integrates seamlessly with both PestPHP and PHPUnit. Start the server in your test setup (e.g., `Server::start()`) and stop it in teardown. It works alongside Laravel’s testing tools, allowing you to mix static mocks (Http::fake()) with dynamic HTTP responses.
- What Laravel versions does guzzlehttp/test-server support?
- The package itself is framework-agnostic but works with any Laravel version supporting PHP 8.1+. It’s designed for modern Laravel apps (8.x+) using Guzzle, Symfony HTTP Client, or custom HTTP logic. No Laravel-specific dependencies exist beyond PHP’s HTTP stack.
- How do I handle Node.js dependencies in CI/CD for this package?
- Use Docker (e.g., `node:22`) or pin Node.js versions in your CI (e.g., `.nvmrc`). Ensure ports are cleaned up post-test (e.g., `Server::stop()` in `register_shutdown_function`). Tools like GitHub Actions or GitLab CI can install Node.js dynamically if needed.
- Is there a way to simulate delayed API responses or sequential calls?
- Yes, use `Server::enqueue()` to queue responses. For delays, enqueue a response with a `sleep()` in a custom middleware or use Node.js’s `setTimeout` via the server’s middleware API. This is useful for testing rate limits or async workflows.
- Can I test WebSocket-like interactions or HTTP/2 with this package?
- The package supports full HTTP/1.1 protocol features, including headers, auth, and redirects. For WebSocket-like interactions, use raw PSR-7 responses with custom headers (e.g., `Upgrade: websocket`). HTTP/2 is not natively supported but can be emulated via headers or middleware.
- How do I validate exact HTTP requests (e.g., headers, body) in tests?
- Use `Server::received()` to inspect requests. Compare request data with `assertEquals` or custom assertions. For complex validation, extend the server’s middleware to log or assert on incoming requests before responding.
- What are the alternatives if I don’t want to manage Node.js?
- For simple Laravel HTTP testing, use `Http::fake()`. For advanced mocking without Node.js, consider WireMock (external server) or VCR (record/replay). Mockery is better for unit testing but lacks HTTP realism. This package strikes a balance between realism and isolation.
- How do I handle port conflicts in CI or local environments?
- Start the server with a dynamic port (e.g., `Server::start(['port' => 0])`) to let the OS assign an available port. Clean up ports in CI using tools like `lsof` or Docker’s port management. Avoid hardcoding ports in tests.
- Can I use this package to test OAuth or JWT authentication flows?
- Yes, simulate OAuth/JWT by enqueuing responses with auth headers (e.g., `Authorization: Bearer token`). Use middleware to validate incoming tokens or modify responses based on request headers. This is ideal for testing auth middleware or client libraries.
Weaver
How can I help you explore Laravel packages today?