Debounce Bundle Laravel Package

Getting Started

• Install as a dev dependency so the fake server is available in tests and local development but not in production:

  composer require --dev vendor/package
  

• Publish the package config if you need to customise ports, fixtures, or default responses:

  php artisan vendor:publish --tag=package-config
  

• Start the fake server for local development. The v1.0.5 release adds a first-class fake server for test and dev, so the quickest first use case is:

  php artisan fake-server:start
  

  Then point your application’s external service base URL at the fake server in .env.local:

  EXTERNAL_API_BASE_URL=http://127.0.0.1:8081
  

• In tests, use the package’s test helper/trait rather than starting a separate process manually. A typical first test looks like:

  use Vendor\Package\Testing\InteractsWithFakeServer;
  
  class ExampleTest extends TestCase
  {
      use InteractsWithFakeServer;
  
      public function test_it_calls_the_external_service(): void
      {
          $this->fakeServer()->respond('/orders', ['id' => 123]);
  
          $this->post('/orders')->assertOk();
  
          $this->fakeServer()->assertRequested('/orders', 'POST');
      }
  }
  

• Look first at the package’s testing helpers and the fake-server config block. The v1.0.5 feature is primarily about replacing brittle HTTP mocking with a real local endpoint that your application can call over HTTP.

Implementation Patterns

• Use the fake server for integration tests, not pure unit tests. For simple response stubbing inside a single class, Laravel’s Http::fake() is still lighter. Use the fake server when you need real HTTP behaviour: middleware, retries, timeouts, streaming, or SDKs that do not use Laravel’s HTTP client.
• Boot per test class or per test. Prefer a trait that starts the server in setUp() and stops it in tearDown(). If the server starts once per process, reset its state between tests:

  protected function setUp(): void
  {
      parent::setUp();
      $this->fakeServer()->reset();
  }
  

• Define responses as fixtures. Keep request/response fixtures in tests/Fixtures/FakeServer/ and register them in a service provider or test helper. This keeps test bodies focused on behaviour rather than payloads.
• Drive local development through env configuration. Run the fake server as a separate process and set the external service URL in .env.local. Avoid hard-coding the fake server URL in application code.
• Use dynamic ports in parallel test runs. If your test suite uses php artisan test --parallel, configure the fake server to bind to an ephemeral port and expose the chosen URL to the test process. A fixed port will collide across parallel workers.
• Use request assertions for contract testing. Assert method, path, headers, and body shape against the fake server’s recorded requests. This catches accidental changes to outbound calls without needing access to the real service.
• Simulate failures deliberately. Configure the fake server to return error status codes, malformed payloads, or delayed responses to exercise retry and timeout logic. Keep these scenarios in named fixture helpers.
• Integrate with CI as a background process or in-process helper. If the test helper starts the server in-process, no CI service is needed. If it starts a separate process, add a CI step that waits for the port to be ready before running tests.
• Guard local-only behaviour. Only start the fake server automatically in the local and testing environments. Do not register fake-server routes or service providers in production.

Gotchas and Tips

• Port collisions are the most common failure. Prefer random or ephemeral ports and read the actual bound port from the package after startup. Do not assume 8080 is free.
• State leaks between tests. The fake server may retain recorded requests and configured responses across tests. Always reset state in setUp() or tearDown(), and stop the server even when a test fails.
• Config caching can mask URL changes. If you change the fake server URL in .env while using php artisan config:cache, remember to clear and rebuild the config cache. In tests, set the base URL through config() or the test environment rather than relying on cached values.
• Lifecycle management matters. A fake server started in a test bootstrap may outlive the test process if teardown is not registered. Use the package’s provided lifecycle helpers where possible, and register shutdown cleanup as a fallback.
• The fake server is not a full mock. It exercises real HTTP, which is its strength, but it will not automatically validate your application’s internal expectations. Pair it with assertions on recorded requests and application state.
• Timeouts and retries need explicit configuration. If your application retries failed requests, make sure the fake server can return failures deterministically and that tests do not accidentally wait for real timeout durations.
• Debugging outbound calls is easier with request logging. Enable the fake server’s request log in failing tests or local development, and dump recorded requests when assertions fail.
• Extension points are useful for custom protocols. If the package exposes custom route handlers or response factories, use them for SDK-specific behaviour rather than modifying package internals.
• Keep fake fixtures versioned with the application. When the external API contract changes, update fixtures alongside the integration code so the fake server continues to represent reality.
• Do not use the fake server as a production dependency. Install it as a dev dependency and keep its service provider and routes out of production.