Testly Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require crudly/testly --dev
   

   Add to composer.json under require-dev if not auto-detected.

2. First Use Case Test a simple Laravel route with a basic assertion:

   use Testly\Testly;
   
   Testly::test('GET /api/users', function () {
       $response = $this->get('/api/users');
       $response->assertStatus(200);
   });
   

3. Where to Look First

   • Documentation: Check the GitHub README (if available) for basic usage.
   • Testly Facade: Explore Testly::test() and Testly::assert() methods in vendor/crudly/testly/src/Testly.php.
   • Examples: Look for tests/ or examples/ in the package directory (if provided).

Implementation Patterns

Workflows

1. Basic HTTP Testing

   Testly::test('User login', function () {
       $response = $this->post('/login', ['email' => '[email protected]', 'password' => 'password']);
       $response->assertRedirect('/dashboard');
   });
   

2. Database Testing

   Testly::test('Create user', function () {
       $user = User::factory()->create();
       $this->assertDatabaseHas('users', ['email' => $user->email]);
   });
   

3. Integration with Laravel Testing Use alongside Laravel’s built-in testing tools (e.g., Http, DatabaseMigrations traits):

   use Illuminate\Foundation\Testing\RefreshDatabase;
   
   Testly::test('User creation with refresh', function () {
       $this->actingAs(User::factory()->create());
       $this->post('/api/users', ['name' => 'John']);
       $this->assertDatabaseCount('users', 2);
   })->uses(RefreshDatabase::class);
   

4. Custom Assertions Extend Testly’s assertions (if supported):

   Testly::assertJsonContains('key', 'expected_value');
   

Integration Tips

• Leverage Laravel’s Testing Helpers: Combine with create(), factory(), or assertJson() for richer tests.
• Group Tests: Use Testly::group() (if available) to organize related tests:

  Testly::group('User', function () {
      Testly::test('Create user');
      Testly::test('Update user');
  });
  

• Mocking: Use Laravel’s Mockery or partialMock within Testly tests:

  Testly::test('Mocked service', function () {
      $mock = Mockery::mock('alias:Service');
      $mock->shouldReceive('process')->once();
      // Test logic...
  });
  

Gotchas and Tips

Pitfalls

1. Outdated Package

   • Last release in 2020 may lack compatibility with newer Laravel versions (e.g., 10.x).
   • Fix: Check composer.json for Laravel version constraints or fork the package.

2. Limited Documentation

   • No stars or issues suggest minimal community support. Assume undocumented behavior.
   • Tip: Inspect src/ for undocumented features (e.g., hidden assertion methods).

3. No Built-in Test Runner

   • Unlike Laravel’s phpunit.xml, Testly may not integrate with Laravel’s test runner.
   • Workaround: Run tests via php artisan test or manually via Testly::run().

4. Stateful Tests

   • Shared state between tests can cause flakiness (e.g., database changes).
   • Solution: Use RefreshDatabase or withoutMiddleware() as needed.

Debugging

• Enable Debug Mode:

  Testly::debug(true); // If supported; check package source.
  

• Log Output:

  Testly::test('Debug test', function () {
      \Log::info('Test context', ['response' => $this->response->getContent()]);
  });
  

• Check Underlying Laravel Tests: If Testly wraps Laravel’s testing, debug using Laravel’s tools:

  php artisan test --debug
  

Extension Points

1. Custom Assertions Extend the package by adding methods to Testly:

   // In a service provider or trait:
   Testly::macro('assertCustom', function ($condition) {
       if (!$condition) {
           throw new \Exception('Custom assertion failed');
       }
   });
   

2. Hooks If Testly supports hooks (e.g., before, after), use them for setup/teardown:

   Testly::before(function () {
       $this->withoutExceptionHandling();
   });
   

3. Configuration Check for a config/testly.php file (if provided) to tweak behavior:

   'default_headers' => [
       'Accept' => 'application/json',
   ],
   

Pro Tips

• Hybrid Testing: Use Testly for high-level flows and Laravel’s HttpTests for granular assertions.
• Performance: Testly may add overhead; reserve for critical paths.
• Fallback: For missing features, drop into raw Laravel testing:

  $this->get('/route')->assertOk(); // Native Laravel syntax.