Getting Started

Minimal Steps

Install the Package Add the package to your project via Composer:
```
composer require --dev testo/lifecycle
```

Enable the Plugin Register the lifecycle plugin in your Testo configuration (typically in testo.php or via CLI):

use Testo\Lifecycle\LifecyclePlugin;

return [
    'plugins' => [
        LifecyclePlugin::class,
    ],
];

First Use Case: Basic Hooks Annotate a test class with lifecycle hooks:

use Testo\Annotations\BeforeClass;
use Testo\Annotations\AfterClass;
use Testo\Annotations\Before;
use Testo\Annotations\After;

#[BeforeClass]
public function setUpClass(): void
{
    // Runs once before all tests in the class
    $this->sharedResource = new SharedResource();
}

#[AfterClass]
public function tearDownClass(): void
{
    // Runs once after all tests in the class
    $this->sharedResource->cleanup();
}

#[Before]
public function setUp(): void
{
    // Runs before each test
    $this->testData = $this->generateTestData();
}

#[After]
public function tearDown(): void
{
    // Runs after each test
    unset($this->testData);
}

public function test_example(): void
{
    // Your test logic
}

Run Tests Execute your tests using Testo’s CLI:
```
./vendor/bin/testo
```

Implementation Patterns

Usage Patterns

Class-Level Lifecycle Management Use @BeforeClass and @AfterClass for setup/teardown that should run once per test class (e.g., database connections, API clients, or heavy fixtures).

#[BeforeClass]
public function createTestDatabase(): void
{
    $this->db = new TestDatabase();
    $this->db->seed();
}

#[AfterClass]
public function dropTestDatabase(): void
{
    $this->db->drop();
}

Per-Test Lifecycle Management Use @Before and @After for setup/teardown that should run before/after each test (e.g., temporary files, mocks, or test-specific data).

#[Before]
public function setUpTestData(): void
{
    $this->testUser = User::factory()->create();
}

#[After]
public function deleteTestData(): void
{
    $this->testUser->delete();
}

Conditional Hooks Dynamically enable/disable hooks based on test conditions or environment variables:

#[Before]
public function conditionalSetup(): void
{
    if (getenv('TEST_WITH_MOCKS')) {
        $this->mockService = $this->createMock(Service::class);
    }
}

Dependency Injection Inject dependencies into lifecycle methods via Testo’s DI container:

#[BeforeClass]
public function setUpWithDependencies(Logger $logger): void
{
    $this->logger = $logger;
    $this->logger->info('Setting up test class');
}

Shared Fixtures Use class-level hooks to load shared fixtures for all tests in a class:

#[BeforeClass]
public function loadSharedFixtures(): void
{
    FixtureLoader::load('shared_fixtures.yaml');
}

Workflows

Fixture-Driven Testing
- Use @BeforeClass to load fixtures once per class.
- Use @AfterClass to clean up fixtures.
- Example: Database seeding for integration tests.
Resource Management
- Use @Before to open connections/files/services.
- Use @After to close/clean up resources.
- Example: Temporary file handling or API client sessions.
Test Isolation
- Ensure each test starts with a clean state by resetting dependencies in @Before.
- Clean up after each test in @After to avoid side effects.
Hybrid Testing
- Combine lifecycle hooks with Testo’s built-in features like async tests or mocking.
- Example: Set up a mock HTTP client in @BeforeClass and use it across tests.

Integration Tips

Leverage Testo’s Annotations Familiarize yourself with Testo’s annotation system (@test, @group, etc.) to combine lifecycle hooks with other test metadata.
Combine with Testo Plugins Integrate testo/lifecycle with other Testo plugins (e.g., testo/database for database testing) for seamless workflows:
```
use Testo\Database\DatabasePlugin;

return [
    'plugins' => [
        DatabasePlugin::class,
        LifecyclePlugin::class,
    ],
];
```

Custom Hook Logic Extend the lifecycle behavior by creating custom methods and calling them from hooks:

#[Before]
public function prepareTestEnvironment(): void
{
    $this->setupMocks();
    $this->configureTestData();
}

private function setupMocks(): void
{
    // Custom mock setup logic
}

Test Organization Group related tests into classes and use @BeforeClass/@AfterClass to manage shared resources efficiently.
CI/CD Optimization Use lifecycle hooks to optimize test runs in CI by:
- Setting up expensive resources once per class (@BeforeClass).
- Parallelizing test execution where possible (Testo supports parallel tests).

Gotchas and Tips

Pitfalls

Hook Execution Order
- Class-level hooks (@BeforeClass, @AfterClass) run once per class, while per-test hooks (@Before, @After) run before/after each test.
- Ensure @BeforeClass completes before @Before and @AfterClass runs after @After.
- Pitfall: Forgetting that @AfterClass runs after all tests, including failures.
State Leakage
- Avoid storing shared state in class properties between tests unless explicitly managed in hooks.
- Pitfall: Accidentally leaving resources open or data modified between tests.
Exception Handling
- Exceptions in lifecycle methods will fail the entire test suite unless caught and handled gracefully.
- Pitfall: Unhandled exceptions in @BeforeClass can prevent tests from running.
Annotation Conflicts
- Ensure annotations are correctly placed (e.g., @Before must be on a method, not a property).
- Pitfall: Misplaced annotations may be ignored or cause errors.
Plugin Compatibility
- Some Testo plugins may interfere with lifecycle hooks. Test thoroughly after adding new plugins.
- Pitfall: Unexpected behavior if plugins override or modify lifecycle execution.
Performance Overhead
- Overusing @Before/@After for lightweight operations can slow down tests.
- Pitfall: Adding unnecessary hooks for trivial setup/teardown.

Debugging

Hook Not Triggering
- Verify the plugin is registered in testo.php.
- Check for syntax errors in annotations (e.g., typos in #[]).
- Debug Tip: Use Testo\Annotations\Before directly in code to test hook execution:
```
#[Before]
public function debugHook(): void
{
    error_log('Hook executed!');
}
```

Hook Failing Silently

Wrap hook logic in try-catch blocks to log errors:

#[Before]
public function setupWithErrorHandling(): void
{
    try {
        $this->setupLogic();
    } catch (\Throwable $e) {
        error_log('Setup failed: ' . $e->getMessage());
        throw $e;
    }
}

Test Isolation Issues
- If tests interfere with each other, check for shared state or improper cleanup in @After.
- Debug Tip: Add assertions in @After to verify cleanup:
```
#[After]
public function verifyCleanup(): void
{
    $this->assertNull($this->testData, 'Test data not cleaned up!');
}
```
Plugin Registration Errors
- Ensure LifecyclePlugin::class is correctly spelled and autoloaded.
- Debug Tip: Clear Composer’s cache and reinstall dependencies:
```
composer clear-cache
composer install
```

Config Quirks

Annotation Syntax
- Use shortcut syntax (#[Before]) instead of @Before if your PHP version supports attributes (PHP 8+).
- Quirk: Older PHP versions may require the @ syntax.
Method Visibility
- Lifecycle methods must be public to be detected by the plugin.
- Quirk: Protected/private methods are ignored.
Static vs. Instance Methods
- Lifecycle methods **must be

Lifecycle Laravel Package