pigui/landing-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update
Some checks failed
Tests / lint (push) Has been cancelled
Details
Tests / test (push) Has been cancelled
Details
Tests / test-postgres (push) Has been cancelled
Details

Browse Source
This commit is contained in:
Josep
2026-08-21 09:14:51 +02:00
parent 618d3a56ad
commit c8ba8d7b14
5 changed files with 388 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

179
tests/Feature/Api/AdminApiContractTest.php Normal file
View File

@@ -0,0 +1,179 @@
<?php
declare(strict_types=1);
namespace Tests\Feature\Api;
use App\Models\Category;
use App\Models\Page;
use App\Models\User;
use Database\Seeders\RolePermissionSeeder;
use Illuminate\Foundation\Testing\RefreshDatabase;
use PHPUnit\Framework\Attributes\Test;
use Tests\FakesPireon;
use Tests\TestCase;
use Tests\VerifiesOpenApiContract;
/**
* The administration API answers with what the specification says it does —
* `PublicApiContractTest`'s other half.
*
* The frontend reads the public document from another repository, in a
* framework not yet chosen; whoever writes it will never see this code, only
* the specification. That case does not apply here — an admin API caller is
* inside this codebase, or at least inside this organisation — but the
* underlying failure is identical: a field renamed in a `Http\Resources\*`
* class is a change nothing else in this suite notices, because every other
* test exercises behaviour, not shape.
*
* Unlike the public listings, an admin index and its matching show endpoint
* send the same full record — none of the four resources here has a
* "lightweight for a listing" projection — so both are held to the stricter
* rule throughout: everything documented and not `nullable` must be present.
*/
class AdminApiContractTest extends TestCase
{
use FakesPireon, RefreshDatabase, VerifiesOpenApiContract;
protected User $caller;
protected function setUp(): void
{
parent::setUp();
$this->loadOpenApiSpec();
$this->seed(RolePermissionSeeder::class);
// super_admin, so a permission gap never masquerades as a shape
// mismatch: every request here must reach the resource, not a 403.
$this->caller = User::factory()->create();
$this->caller->syncRoles(['super_admin']);
$this->withHeaders($this->apiHeadersFor($this->caller));
}
/**
* @return array<string, array{path: string}>
*/
public static function paginatedEndpoints(): array
{
return [
'pages' => ['path' => '/v1/pages'],
'categories' => ['path' => '/v1/categories'],
'users' => ['path' => '/v1/users'],
];
}
#[Test]
public function every_admin_record_answers_in_the_shape_it_documents(): void
{
$page = Page::factory()->create();
$category = Category::factory()->create();
// One request, one documented path — the URL a real caller hits and
// the path key that describes it, side by side rather than derived
// from one another, because guessing the second from the first is
// exactly the kind of cleverness that breaks quietly.
$cases = [
'pages' => ['/v1/pages', '/v1/pages'],
'page' => ["/v1/pages/{$page->id}", '/v1/pages/{page}'],
'categories' => ['/v1/categories', '/v1/categories'],
'category' => ["/v1/categories/{$category->id}", '/v1/categories/{category}'],
'users' => ['/v1/users', '/v1/users'],
'user' => ["/v1/users/{$this->caller->id}", '/v1/users/{user}'],
'me' => ['/v1/me', '/v1/me'],
'roles' => ['/v1/roles', '/v1/roles'],
];
$problems = [];
foreach ($cases as $name => [$url, $documentedPath]) {
$response = $this->getJson('/api'.$url);
if ($response->status() !== 200) {
$problems[] = "{$name}: answered {$response->status()}";
continue;
}
$payload = $response->json('data');
$record = array_is_list((array) $payload) ? ($payload[0] ?? null) : $payload;
if (! is_array($record)) {
$problems[] = "{$name}: no record to compare against";
continue;
}
$schema = $this->recordSchema($documentedPath);
foreach (array_diff(array_keys($record), $this->documentedKeys($schema)) as $undocumented) {
$problems[] = "{$name}: sends `{$undocumented}`, which the specification does not describe";
}
foreach (array_diff($this->alwaysPresent($schema), array_keys($record)) as $missing) {
$problems[] = "{$name}: documents `{$missing}`, which it does not send";
}
}
$this->assertSame([], $problems, "The admin API and its specification disagree:\n".implode("\n", $problems));
}
/**
* The pagination envelope every listing here uses — `data`, `links`,
* `meta` — checked the same way the record inside it is: nothing sent
* that is not documented.
*
* Worth its own test rather than folding into the one above: the record
* comparison already proves the endpoints work at all, and a failure here
* points at a completely different place to fix — the collection schema,
* not a `Resource` class.
*/
#[Test]
public function the_pagination_envelope_matches_what_is_documented(): void
{
Page::factory()->create();
Category::factory()->create();
$problems = [];
foreach (self::paginatedEndpoints() as $name => $endpoint) {
$response = $this->getJson('/api'.$endpoint['path'])->assertOk();
$envelope = $this->responseSchema($endpoint['path']);
$documented = $this->documentedKeys($envelope);
foreach (array_diff(array_keys($response->json()), $documented) as $undocumented) {
$problems[] = "{$name}: envelope sends `{$undocumented}`, which the specification does not describe";
}
$metaSchema = $this->resolve($envelope['properties']['meta'] ?? []);
$meta = (array) $response->json('meta');
foreach (array_diff(array_keys($meta), $this->documentedKeys($metaSchema)) as $undocumented) {
$problems[] = "{$name}: meta sends `{$undocumented}`, which the specification does not describe";
}
foreach (array_diff($this->alwaysPresent($metaSchema), array_keys($meta)) as $missing) {
$problems[] = "{$name}: meta documents `{$missing}`, which it does not send";
}
}
$this->assertSame([], $problems, "The pagination envelope and its specification disagree:\n".implode("\n", $problems));
}
/**
* `/v1/roles` is the one listing here Laravel never paginates —
* `RoleController::index()` calls `->get()`, not `->paginate()` — so
* proving it carries no stray `meta`/`links` is the other half of the
* envelope test above.
*/
#[Test]
public function the_unpaginated_roles_listing_carries_no_pagination_envelope(): void
{
$response = $this->getJson('/api/v1/roles')->assertOk();
$this->assertSame(['data'], array_keys($response->json()));
}
}

102
tests/Feature/Api/PublicApiContractTest.php
View File

@@ -15,8 +15,8 @@ use App\Models\Technology;
use App\Models\Testimonial;
use Illuminate\Foundation\Testing\RefreshDatabase;
use PHPUnit\Framework\Attributes\Test;
use Symfony\Component\Yaml\Yaml;
use Tests\TestCase;
use Tests\VerifiesOpenApiContract;
/**
* The public API answers with what the specification says it answers with.
@@ -34,12 +34,7 @@ use Tests\TestCase;
*/
class PublicApiContractTest extends TestCase
{
use RefreshDatabase;
/**
* @var array<string, mixed>
*/
protected array $spec;
use RefreshDatabase, VerifiesOpenApiContract;
protected function setUp(): void
{
@@ -47,7 +42,7 @@ class PublicApiContractTest extends TestCase
$this->withHeaders(['Accept-Language' => 'es']);
$this->spec = (array) Yaml::parseFile(public_path('openapi.yaml'));
$this->loadOpenApiSpec();
}
/**
@@ -171,14 +166,15 @@ class PublicApiContractTest extends TestCase
continue;
}
$documented = $this->documentedKeys($endpoint['path']);
$schema = $this->recordSchema($endpoint['path']);
$documented = $this->documentedKeys($schema);
foreach (array_diff(array_keys($record), $documented) as $undocumented) {
$problems[] = "{$name}: sends `{$undocumented}`, which the specification does not describe";
}
if ($endpoint['detail']) {
foreach (array_diff($this->alwaysPresent($endpoint['path']), array_keys($record)) as $missing) {
foreach (array_diff($this->alwaysPresent($schema), array_keys($record)) as $missing) {
$problems[] = "{$name}: documents `{$missing}`, which it does not send";
}
}
@@ -186,90 +182,4 @@ class PublicApiContractTest extends TestCase
$this->assertSame([], $problems, "The public API and its specification disagree:\n".implode("\n", $problems));
}
/**
* The field names the specification promises for one endpoint's records.
*
* @return array<int, string>
*/
protected function documentedKeys(string $path): array
{
return array_keys($this->recordSchema($path)['properties'] ?? []);
}
/**
* The schema of a single record, whichever way the endpoint wraps it.
*
* @return array<string, mixed>
*/
protected function recordSchema(string $path): array
{
$schema = $this->resolve(
$this->spec['paths'][$path]['get']['responses'][200]['content']['application/json']['schema'] ?? [],
);
$data = $this->resolve($schema['properties']['data'] ?? []);
// A listing documents its records under `items`; a detail endpoint
// describes them directly.
if (($data['type'] ?? null) === 'array') {
$data = $this->resolve($data['items'] ?? []);
}
return $data;
}
/**
* The documented fields a detail endpoint must always answer with.
*
* Anything the specification marks `nullable` is left out of this half of
* the check. That is the vocabulary this document already uses for a field
* that may not be there — a member's `role` exists only while they are
* nested under a project, and the schema says so. The other direction
* stays strict for every field either way: whatever the API sends has to
* be described, nullable or not.
*
* @return array<int, string>
*/
protected function alwaysPresent(string $path): array
{
$record = $this->recordSchema($path);
return array_keys(array_filter(
(array) ($record['properties'] ?? []),
fn (array $property) => ($property['nullable'] ?? false) !== true,
));
}
/**
* Follow `$ref` and flatten `allOf`, which is how the specification says
* "this, plus a couple of fields" without repeating a schema.
*
* @param array<string, mixed> $schema
* @return array<string, mixed>
*/
protected function resolve(array $schema): array
{
if (isset($schema['$ref'])) {
$name = basename((string) $schema['$ref']);
return $this->resolve((array) ($this->spec['components']['schemas'][$name] ?? []));
}
if (isset($schema['allOf'])) {
$merged = ['type' => 'object', 'properties' => []];
foreach ((array) $schema['allOf'] as $part) {
$resolved = $this->resolve((array) $part);
$merged['properties'] = [
...$merged['properties'],
...($resolved['properties'] ?? []),
];
}
return [...$schema, ...$merged];
}
return $schema;
}
}

131
tests/VerifiesOpenApiContract.php Normal file
View File

@@ -0,0 +1,131 @@
<?php
declare(strict_types=1);
namespace Tests;
use Symfony\Component\Yaml\Yaml;
/**
* Compares an actual JSON response against what `public/openapi.yaml` says
* it should look like.
*
* Shared between the public and the admin contract tests because the
* question is the same one twice: does the shape the document promises match
* the shape the API sends. What differs between the two is everything
* *around* the question — how a caller authenticates, what a listing is
* allowed to leave out — not the comparison itself.
*/
trait VerifiesOpenApiContract
{
/**
* @var array<string, mixed>
*/
protected array $spec;
protected function loadOpenApiSpec(): void
{
$this->spec = (array) Yaml::parseFile(public_path('openapi.yaml'));
}
/**
* The field names a schema promises, one level deep — enough for a flat
* comparison against `array_keys()` on a decoded JSON object.
*
* @return array<int, string>
*/
protected function documentedKeys(array $schema): array
{
return array_keys($this->resolve($schema)['properties'] ?? []);
}
/**
* The documented fields that must always be present.
*
* Anything the specification marks `nullable` is left out of this half of
* the check — that is the vocabulary this document already uses for a
* field that may not be there, whether because the value itself can be
* null or because it only appears down one particular route. The other
* direction stays strict regardless: whatever is actually sent has to be
* described, nullable or not.
*
* @return array<int, string>
*/
protected function alwaysPresent(array $schema): array
{
$resolved = $this->resolve($schema);
return array_keys(array_filter(
(array) ($resolved['properties'] ?? []),
fn (array $property) => ($property['nullable'] ?? false) !== true,
));
}
/**
* The schema of one record inside a `{"data": ...}` envelope, whichever
* way the endpoint wraps it — a bare object for a detail endpoint, or the
* `items` of an array for a listing.
*
* @return array<string, mixed>
*/
protected function recordSchema(string $path, string $method = 'get', int $status = 200): array
{
$schema = $this->resolve(
$this->spec['paths'][$path][$method]['responses'][$status]['content']['application/json']['schema'] ?? [],
);
$data = $this->resolve($schema['properties']['data'] ?? []);
if (($data['type'] ?? null) === 'array') {
$data = $this->resolve($data['items'] ?? []);
}
return $data;
}
/**
* Everything documented for one path's response, `data` included — for
* comparing against the envelope as a whole rather than only the record
* inside it.
*
* @return array<string, mixed>
*/
protected function responseSchema(string $path, string $method = 'get', int $status = 200): array
{
return $this->resolve(
$this->spec['paths'][$path][$method]['responses'][$status]['content']['application/json']['schema'] ?? [],
);
}
/**
* Follow `$ref` and flatten `allOf`, which is how the specification says
* "this, plus a couple of fields" without repeating a schema.
*
* @param array<string, mixed> $schema
* @return array<string, mixed>
*/
protected function resolve(array $schema): array
{
if (isset($schema['$ref'])) {
$name = basename((string) $schema['$ref']);
return $this->resolve((array) ($this->spec['components']['schemas'][$name] ?? []));
}
if (isset($schema['allOf'])) {
$merged = ['type' => 'object', 'properties' => []];
foreach ((array) $schema['allOf'] as $part) {
$resolved = $this->resolve((array) $part);
$merged['properties'] = [
...$merged['properties'],
...($resolved['properties'] ?? []),
];
}
return [...$schema, ...$merged];
}
return $schema;
}
}