Scrutineer Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require codeheures-fr/scrutineer
   

   Publish the configuration (if needed):

   php artisan vendor:publish --provider="Scrutineer\ScrutineerServiceProvider"
   

2. Basic Usage Register a test case in your Laravel routes or controller:

   use Scrutineer\Scrutineer;
   
   Route::get('/test-route', function () {
       return Scrutineer::test('Test Route', function () {
           // Your manual test steps here
           return view('test-view');
       });
   });
   

3. First Test Case Create a dedicated route (e.g., /scrutineer) to access the console:

   Route::get('/scrutineer', [ScrutineerController::class, 'index']);
   

   Define a simple test in ScrutineerController:

   public function index()
   {
       return Scrutineer::run(function () {
           Scrutineer::step('Verify Homepage Loads', function () {
               $response = $this->get('/');
               $response->assertStatus(200);
           });
       });
   }
   

Implementation Patterns

Contract-Driven Workflows

1. Define Test Contracts Use Scrutineer::contract() to outline expected behavior before implementation:

   Scrutineer::contract('User Login', [
       'step1' => 'Navigate to login page',
       'step2' => 'Enter valid credentials',
       'step3' => 'Verify dashboard redirect',
   ]);
   

2. Integrate with Laravel Features

   • Authentication: Protect test routes with middleware:

     Route::middleware(['auth'])->group(function () {
         Scrutineer::test('Admin Dashboard', function () {
             // Test admin-only functionality
         });
     });
     

   • Artisan Commands: Trigger tests via CLI:

     use Illuminate\Console\Command;
     
     class RunScrutineerTests extends Command
     {
         protected $signature = 'scrutineer:run';
         public function handle()
         {
             Scrutineer::runAll();
         }
     }
     

3. Step-Based Testing Break tests into reusable steps:

   Scrutineer::step('Add to Cart', function () {
       $this->post('/cart/add', ['product_id' => 1]);
       $this->assertSessionHas('cart_item');
   });
   

4. Data-Driven Tests Use Laravel’s DatabaseSeeder or factories to populate test data:

   Scrutineer::step('Test User Creation', function () {
       $user = User::factory()->create();
       $this->actingAs($user);
       $this->get('/profile')->assertSee($user->email);
   });
   

Gotchas and Tips

Common Pitfalls

1. State Management

   • Tests run in a fresh state by default. Use Scrutineer::withState() to persist data:

     Scrutineer::withState(function () {
         Auth::loginUsingId(1); // Preserve auth state
     });
     

   • Avoid global state pollution (e.g., static variables) between tests.

2. Configuration Quirks

   • Ensure SCRUTINEER_ENABLED is set to true in .env for production-like testing.
   • Customize the console UI via config/scrutineer.php:

     'theme' => 'dark',
     'steps_per_page' => 5,
     

3. Debugging

   • Use Scrutineer::debug() to log intermediate state:

     Scrutineer::step('Debug Response', function () {
         $response = $this->get('/api/data');
         Scrutineer::debug($response->json());
     });
     

   • Check Laravel logs (storage/logs/laravel.log) for failed assertions.

4. Performance

   • Disable slow tests in CI by tagging them:

     Scrutineer::test('Slow Test', function () { ... })->tag('slow');
     

   • Run only tagged tests:

     php artisan scrutineer:run --tag=smoke
     

Extension Points

1. Custom Assertions Extend the test client with helper methods:

   use Scrutineer\ScrutineerTestCase;
   
   class CustomScrutineerTestCase extends ScrutineerTestCase
   {
       public function assertCustomCondition($condition)
       {
           if (!$condition) {
               $this->fail('Custom condition failed');
           }
       }
   }
   

2. Plugin System Hook into the scrutineer.running event to add pre/post-test logic:

   Scrutineer::listen('scrutineer.running', function ($test) {
       // Setup: e.g., mock external APIs
   });
   

3. API Testing Use Laravel’s HTTP tests within Scrutineer::step():

   Scrutineer::step('API Validation', function () {
       $response = $this->json('POST', '/api/login', ['email' => '[email protected]']);
       $response->assertJsonStructure(['data' => ['token']]);
   });