Package · cast

Testing

MockTransport replaces the network: it answers from a queue and records what was sent. Everything above the network stays real.

MockTransport

php
use Flytachi\Winter\Cast\Client\CastClient;
use Flytachi\Winter\Cast\Message\CastRequest;
use Flytachi\Winter\Cast\Message\CastResponse;
use Flytachi\Winter\Cast\Transport\MockTransport;

public function testCreatesAnOrder(): void
{
  $mock = new MockTransport(
      CastResponse::fromJson(['id' => 7], 201),
  );
  $client = CastClient::create()->withBaseUrl('https://shop.test/api')->withTransport($mock);

  $id = (new OrderService($client))->create(['sku' => 'A-1']);

  self::assertSame(7, $id);
  self::assertSame('POST', $mock->lastRequest()->getMethod());
  self::assertSame('https://shop.test/api/orders', (string) $mock->lastRequest()->getUri());
  self::assertSame('{"sku":"A-1"}', (string) $mock->lastRequest()->getBody());
}

The base URL, default headers, middleware, retries, redirects and throwOnError all stay real. So the test checks exactly what would go to the server.

What can be queued

Entry What happens
CastResponse returned as the response
a function fn(CastRequest $request, TransferOptions $options) called, returns the response — for responses that depend on the request
an exception (Throwable) thrown
MockTransport::fail() fails like a dropped connection: NetworkException
php
$mock = new MockTransport(
  MockTransport::fail(),                                   // first attempt — dropped
  CastResponse::fromString('', 503, ['Retry-After' => '0']),
  fn(CastRequest $r) => CastResponse::fromJson(['path' => $r->getUri()->getPath()]),
);
$mock->append(CastResponse::fromString('ok'));               // add to the end

MockTransport::fail($message, $curlErrno): by default code 7, “could not connect” — RetryPolicy treats that error as transient and retries it. Pass another code to test an error that is not retried.

When the queue runs out, the next send fails with a CastException that names the request left without a response.

Checking what was sent

Method What it gives
requests() every request sent, in order — each attempt and each redirect hop
lastRequest() the last one
remaining() how many responses are left in the queue; 0 at the end of a test means all were used
php
self::assertCount(2, $mock->requests());                    // there was one retry
self::assertSame(0, $mock->remaining());
self::assertSame('Bearer t', $mock->requests()[0]->getHeaderLine('Authorization'));

Responses for tests

php
CastResponse::fromJson(['id' => 1]);                          // 200, Content-Type: application/json
CastResponse::fromJson(['error' => 'taken'], 409);
CastResponse::fromString('<html>', 502, ['Content-Type' => 'text/html']);
new CastResponse(204);

Scenarios

Retries:

php
$mock = new MockTransport(MockTransport::fail(), CastResponse::fromJson(['ok' => true]));
$client = $client->withTransport($mock)->withRetry(RetryPolicy::fixed(2, 0));

$response = $client->get('ping')->send();
self::assertSame(2, $response->info()->attempts);

A redirect:

php
$mock = new MockTransport(
  CastResponse::fromString('', 302, ['Location' => 'https://cdn.test/file']),
  CastResponse::fromString('data'),
);
// the second request goes to cdn.test and without Authorization

An error status:

php
$mock = new MockTransport(CastResponse::fromJson(['message' => 'nope'], 422));

$this->expectException(ClientErrorException::class);
(new OrderService($client->withTransport($mock)))->create([]);

The facade in tests

If the code under test uses the facade, replace its client and restore it after the test:

php
protected function setUp(): void
{
  $this->mock = new MockTransport();
  Cast::setClient(CastClient::create()->withTransport($this->mock));
}

protected function tearDown(): void
{
  Cast::setClient(null);   // the next call creates the default client
}