Getting Started

Minimal Steps

Installation Add the package as a dev dependency in your Laravel project:
```
composer require --dev dansan/jobboy-test-pack
```
Ensure your composer.json includes it under require-dev.

First Use Case Leverage pre-built test jobs to validate job processing logic:

use Dansan\JobBoyTestPack\Jobs\TestJob;

public function test_job_processing()
{
    $job = new TestJob();
    $this->assertTrue($job->isTestJob());
    $this->assertEquals('default', $job->getHandler());
}

Where to Look First
- src/Jobs/: Predefined test jobs (e.g., TestJob, TestJobWithPayload) for immediate use.
- src/Traits/: Shared test traits (e.g., JobAssertions) to reduce boilerplate.
- Documentation: For advanced patterns like mocking queue listeners or simulating failures.

Implementation Patterns

Usage Patterns

Standardizing Job Tests Replace custom job assertions with shared utilities:

use Dansan\JobBoyTestPack\Traits\JobAssertions;

class JobTest extends TestCase
{
    use JobAssertions;

    public function test_job_dispatch()
    {
        $this->assertJobDispatched(TestJob::class);
    }
}

Queue Listener Testing Simulate queue events with TestQueueListener:

use Dansan\JobBoyTestPack\Queue\TestQueueListener;

public function test_listener_handles_job()
{
    $listener = new TestQueueListener();
    $listener->handle(new TestJob());

    $this->assertTrue($listener->wasHandled());
}

Payload Validation Use TestJobWithPayload to validate job data structures:

use Dansan\JobBoyTestPack\Jobs\TestJobWithPayload;

public function test_payload_integrity()
{
    $payload = ['user_id' => 1, 'action' => 'create'];
    $job = new TestJobWithPayload($payload);

    $this->assertEquals($payload, $job->getPayload());
}

Database Transactions in Tests Extend Laravel’s TestCase with shared database setup:

use Dansan\JobBoyTestPack\Database\TestDatabase;

class JobDatabaseTest extends TestCase
{
    use TestDatabase;

    public function test_job_creates_record()
    {
        $this->seedTestDatabase();
        $job = new TestJob();
        $job->handle();

        $this->assertDatabaseHas('jobs', ['job' => 'test_job']);
    }
}

Workflow Integration

CI/CD Optimization Standardize test environments across repositories by enforcing shared test dependencies:

# .github/workflows/test.yml
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: composer install --prefer-dist --no-interaction
      - run: composer require --dev dansan/jobboy-test-pack
      - run: php artisan test

Monorepo Adoption In a monorepo with multiple JobBoy services, add the package to a shared dev-dependencies config:

// monorepo/composer.json
"extra": {
    "monorepo": {
        "packages": {
            "dev-dependencies": {
                "dansan/jobboy-test-pack": "^1.0.0"
            }
        }
    }
}

Test Suite Modularization Group shared test logic into a TestHelper class:

namespace Tests\Helpers;

use Dansan\JobBoyTestPack\Traits\JobAssertions;

class TestHelper
{
    use JobAssertions;

    public static function assertJobProcessed($jobClass)
    {
        // Custom logic using JobAssertions
    }
}

Gotchas and Tips

Pitfalls

Version Conflicts
- Issue: The package may lack explicit version constraints for Laravel or PHPUnit.
- Fix: Pin versions in composer.json:
```
"dansan/jobboy-test-pack": "1.0.0",
"laravel/framework": "^10.0",
"phpunit/phpunit": "^9.5"
```
Undocumented Traits
- Issue: Traits like JobAssertions may assume global state or Laravel services.
- Fix: Review trait methods before use:
```
// Avoid if trait uses undefined services
use Dansan\JobBoyTestPack\Traits\UnstableTrait;
```
Test Pollution
- Issue: Shared test jobs (e.g., TestJob) might conflict with your project’s actual jobs.
- Fix: Rename or alias:
```
use Dansan\JobBoyTestPack\Jobs\TestJob as PackagedTestJob;
```
Database Seed Assumptions
- Issue: TestDatabase trait may seed tables that don’t exist in your project.
- Fix: Extend the trait or override methods:
```
class CustomTestDatabase extends TestDatabase
{
    protected function seedTables()
    {
        // Custom seed logic
    }
}
```

Debugging Tips

Enable Debug Logging Add to config/logging.php to trace package interactions:

'channels' => [
    'jobboy_test_pack' => [
        'driver' => 'single',
        'path' => storage_path('logs/jobboy_test_pack.log'),
        'level' => 'debug',
    ],
],

Isolate Dependencies Use composer why-not to check for conflicts:
```
composer why-not dansan/jobboy-test-pack
```

Test in Isolation Create a dedicated test project to validate the package:

composer create-project laravel/laravel jobboy-test-pack-demo
cd jobboy-test-pack-demo
composer require --dev dansan/jobboy-test-pack

Extension Points

Custom Test Jobs Extend TestJob to add domain-specific logic:

namespace App\Tests\Jobs;

use Dansan\JobBoyTestPack\Jobs\TestJob;

class CustomTestJob extends TestJob
{
    public function getCustomHandler()
    {
        return 'app_handler';
    }
}

Queue Mocking Override TestQueue to simulate custom behaviors:

use Dansan\JobBoyTestPack\Queue\TestQueue;

class CustomTestQueue extends TestQueue
{
    public function dispatchWithDelay($job, $delay)
    {
        // Custom delay logic
    }
}

Assertion Extensions Add project-specific assertions to JobAssertions:

namespace App\Tests\Traits;

use Dansan\JobBoyTestPack\Traits\JobAssertions as BaseJobAssertions;

trait JobAssertions extends BaseJobAssertions
{
    public function assertCustomJobProcessed($jobClass)
    {
        // Custom assertion logic
    }
}

Configuration Quirks

Autoloading Ensure the package’s composer.json includes autoload-dev:
```
"autoload-dev": {
    "psr-4": {
        "Dansan\\JobBoyTestPack\\": "src/"
    }
 }
```
Run composer dump-autoload after installation.

Service Provider If the package includes a service provider, register it in config/app.php:

'providers' => [
    // ...
    Dansan\JobBoyTestPack\JobBoyTestPackServiceProvider::class,
],

Environment Variables Check for required .env variables (e.g., JOBBOY_TEST_PACK_DEBUG=1).

Jobboy Test Pack Laravel Package