Testing Your API
================

Automated testing is essential to ensure your API works as expected and keeps working as you add features. LacePHP provides a simple **Tester** class that simulates HTTP requests against your routes, so you can write quick, readable tests without spinning up an external client or server.

Why Testing Matters
-------------------
- **Confidence:**  
  Catch regressions early when you change code.  
- **Documentation:**  
  Tests show exactly how your API should behave.  
- **Speed:**  
  Run hundreds of route tests in seconds without a real HTTP server.  

Introducing `Tester`
--------------------
The `Lacebox\Sole\Heel\Tester` class gives you a fluent DSL:

.. code-block:: php

   namespace Tests;

   use Lacebox\Sole\Heel\Tester;
   use Lacebox\Sole\Router;

   // Create a tester with your app’s router
   $router = require __DIR__ . '/../routes/api.php';
   $t      = new Tester($router);

   // Simulate a GET request, check status and JSON
   $t->get('/posts')
     ->expect(200)
     ->json([
         ['id'=>1, 'title'=>'First post'],
         ['id'=>2, 'title'=>'Second post'],
     ]);

Key Methods
~~~~~~~~~~~
- **get(string $uri): self**  
  - Simulate `GET $uri`.  
- **expect(int $code): self**  
  - Assert the HTTP status code (e.g. 200, 404).  
- **json(array $expected): self**  
  - Decode the response body as JSON and compare strictly to `$expected`.  
- **raw(): mixed**  
  - Retrieve the raw response (string or array) for custom assertions.  

Basic Example
~~~~~~~~~~~~~
Test the `POST /login` endpoint returns a token:

.. code-block:: php

   <?php
   // tests/LoginTest.php

   use Lacebox\Sole\Heel\Tester;
   use function sole_request;

   $router = require __DIR__ . '/../routes/api.php';
   $t = new Tester($router);

   $t->get('/login?user=alice&pass=secret')
     ->expect(200)
     ->json([
         'token' => 'abc123def456'
     ]);

Checking Error Responses
~~~~~~~~~~~~~~~~~~~~~~~~
You can also assert non-200 codes:

.. code-block:: php

   $t->get('/posts/9999')
     ->expect(404)
     ->raw();  // inspect body or leave as is

Combining Multiple Requests
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Chain multiple scenarios in one script:

.. code-block:: php

   // tests/PostCrudTest.php

   $t->get('/posts')->expect(200)->json([/* all posts */]);

   $t->get('/posts/1')->expect(200)->json([
       'id' => 1,
       'title' => 'First post',
   ]);

   $t->get('/posts/999')->expect(404);

Best Practices
--------------
- **Isolate your data**: run tests against an in-memory or test database.  
- **Reset state**: truncate tables or use dummy transactions.  
- **Group assertions**: one test file per resource or feature.  
- **Use descriptive names**: comments or method names explain each scenario.  


.. warning::

   - `Tester` manipulates `$_SERVER`, `REQUEST_URI` and `http_response_code()`; avoid mixing with real server calls.  
   - Tests run synchronously in PHP, avoid long-running tasks or external HTTP calls inside your routes.  
   - If your route uses session or CSRF, initialise or disable those protections in your test bootstrap.  

By using LacePHP’s `Tester`, you can write clear, fast route tests—making their APIs reliable and easy to maintain.

|
|