Laravel Api Tester Laravel Package

Getting Started

Install it as a dev-only dependency and publish its config/assets:

composer require --dev asvae/laravel-api-tester
php artisan vendor:publish --provider="Asvae\ApiTester\ApiTesterServiceProvider"

Open config/api-tester.php, confirm the route prefix (typically /api-tester), the middleware stack (web by default), and the enabled flag. Then visit:

http://your-app.test/api-tester

The first useful use case is a quick smoke test: pick a JSON API route such as GET /api/v1/users, add Accept: application/json, optionally add an Authorization: Bearer ... header, send it, and inspect status, headers, and body in the same screen. Save the request so you can replay it after changing a controller, route, or validation rule.

Where to look first:

• config/api-tester.php — enablement, prefix, middleware, route registration.
• routes/api.php — the endpoints you will actually exercise.
• app/Http/Kernel.php — whether your API routes use api, auth:sanctum, tenancy, etc.
• storage/logs/laravel.log — when the UI shows an error but the response is opaque.

Implementation Patterns

Keep it local-only. The package is a development convenience, not production tooling. Gate it in config:

// config/api-tester.php
'enabled' => env('API_TESTER_ENABLED', app()->environment('local')),
'prefix'  => 'api-tester',
'middleware' => ['web'],

Add API_TESTER_ENABLED=false to .env.example and never install it with --no-dev deployments.

Use it as an exploratory layer, not a test suite. It complements PHPUnit/Pest feature tests. Exploratory requests find shape mismatches, auth problems, and validation messages; feature tests keep CI honest.

Organize saved requests by resource. Save one request per endpoint (GET /users, POST /users, PATCH /users/{id}) and keep IDs in a note or a variable. Seed deterministic data first:

php artisan migrate:fresh --seed

Then use known IDs from the seeder so saved requests remain replayable.

Auth patterns. Two common approaches:

• Token-based: generate a Sanctum/Passport token and paste it into an Authorization: Bearer <token> header.
• Session-based: log into the app in the same browser, then send requests with the session cookie. This only works if the tester shares the same domain/session middleware.

For multi-tenant or header-driven APIs, add the tenant header (X-Tenant: ...) to a saved request or to the default headers in config. For Sanctum SPA auth, prefer a token over cookie auth to avoid SameSite/CSRF surprises.

Parameterize with path variables and JSON bodies. Keep the request body in the UI as a JSON template:

{
  "name": "Test User",
  "email": "test+{{id}}@example.com"
}

Swap the ID between runs. For endpoints that mutate state, save a “create” request first and copy the returned ID into the follow-up GET/PATCH/DELETE requests.

Route visibility. After adding routes, clear caches:

php artisan route:clear
php artisan config:clear

If your API routes are registered conditionally (e.g., only when routes/api.php is loaded), make sure the tester’s environment loads them.

Middleware integration. Point the tester at the same middleware your real API uses, or add a thin dev-only middleware that injects a known user:

// app/Http/Middleware/ApiTesterAuth.php
public function handle($request, Closure $next)
{
    if (app()->environment('local')) {
        auth()->loginUsingId(1);
    }
    return $next($request);
}

This makes authenticated endpoints callable without manually copying tokens. Keep this middleware local-only.

Use alongside php artisan serve and Telescope. Telescope shows the underlying query/exception detail when the tester’s UI only shows a 500. Use both when debugging.

Gotchas and Tips

• The package is stale. Last release was 2020-09-19. It predates Laravel 8+ conventions and PHP 8 typed properties in some places. Expect friction on modern Laravel; test installation early and be prepared to fork or pin versions:

  composer require --dev asvae/laravel-api-tester --with-all-dependencies
  

  If Composer refuses due to PHP/Laravel constraints, fork the repo, relax composer.json, and require your fork via a VCS repository.

• Never expose it in production. Even with enabled, verify the route is not reachable on staging/production. The UI can send authenticated requests; treat it like a debug console.

• CSRF can break POST/PUT/PATCH. If the tester uses the web middleware group, state-changing requests may hit VerifyCsrfToken. Either configure an API-style middleware stack for the tester or ensure the UI sends the CSRF token. When in doubt, use api middleware and token auth.

• Empty route list usually means caching or environment. Run route:clear and confirm APP_ENV is local. Also check that API routes are actually registered in RouteServiceProvider.

• JSON body ignored without the right Content-Type. Always set Content-Type: application/json and Accept: application/json on saved JSON requests. Otherwise Laravel may treat the body as form input and $request->json() will be empty.

• File uploads and multipart are painful. The tester is best for JSON. Use Postman/Insomnia for multipart uploads, streaming, or binary responses.

• Large or streamed responses can hang the UI. For export endpoints or huge payloads, test with curl instead. The browser panel is not built for pagination-heavy or chunked responses.

• Config changes require a cache clear. php artisan config:clear after changing enabled, prefix, or middleware. If you run config:cache locally, the tester may appear disabled unexpectedly.

• Debugging checklist: browser devtools Network tab → storage/logs/laravel.log → Telescope → php artisan route:list | grep api. Most “it doesn’t work” cases are auth middleware, CSRF, or route caching.

• Extension points are limited but usable. Publish the views and config to customize branding/default headers; add middleware for auth injection; fork the service provider if you need route filtering. Because the project is effectively unmaintained, keep customizations minimal and isolated so you can drop it for a maintained alternative (e.g., Scramble, Scribe, or plain HTTP files) later.

• Don’t make it a team dependency. With zero dependents and no recent releases, treat it as a personal convenience. If a teammate cannot install it on Laravel 10/11, they should not be blocked — document the equivalent curl/Pest snippets in the repo.