Getting Started

Minimal Steps

Install the Package Add to composer.json under require-dev:
```
composer require --dev testo/filter
```
Ensure your project uses Testo as the test framework (not PHPUnit/Pest).

Basic CLI Usage Run filtered tests via Testo’s CLI flags:

vendor/bin/testo run --filter="UserTest"          # Filter by test name
vendor/bin/testo run --path="tests/integration"   # Filter by test path
vendor/bin/testo run --suite="auth"               # Filter by suite
vendor/bin/testo run --type="unit"                # Filter by test type
vendor/bin/testo run --dataset="users:premium"    # Filter by dataset

First Use Case: Debugging a Specific Test Replace running the entire suite with:
```
vendor/bin/testo run --filter="test_login_fails_with_invalid_credentials"
```

Where to Look First

Testo Documentation (filter plugin section).
testo/filter source (under plugin/filter/ in the main monorepo) for advanced customization.
CLI flags (--help) for available filtering options.

Implementation Patterns

Usage Patterns

1. CLI-Driven Filtering

Workflow: Use Testo’s CLI flags in composer.json scripts or CI/CD pipelines.

"scripts": {
  "test:unit": "vendor/bin/testo run --type=unit",
  "test:integration": "vendor/bin/testo run --path=\"tests/integration\"",
  "test:debug": "vendor/bin/testo run --filter=\"LoginTest\""
}

CI/CD Example (GitHub Actions):

- name: Run filtered tests
  run: vendor/bin/testo run --path="tests/changed_files"

2. Programmatic Filtering (Advanced)

Use Case: Dynamically filter tests in a custom test runner or Artisan command.

Example: Create a service to parse and apply filters:

use Testo\Filter\Filter;

class TestFilterService {
    public function apply(string $filterPattern): array {
        $filter = new Filter();
        return $filter->match($filterPattern); // Returns matched test cases
    }
}

Integration with Laravel: Bind the service in AppServiceProvider:

$this->app->singleton(TestFilterService::class, function () {
    return new TestFilterService();
});

3. Dataset Filtering

Use Case: Run tests with specific dataset pointers (e.g., @dataset("users:premium")).

CLI:

vendor/bin/testo run --dataset="users:premium" --dataset="orders:cancelled"

Programmatic:

$filter->matchDataset("users:premium"); // Custom logic to filter by dataset

4. Suite-Based Execution

Use Case: Group related tests into suites (e.g., auth, payments) and run them selectively.

Define Suites in testo.php config:

return [
    'suites' => [
        'auth' => ['tests/unit/Auth/*', 'tests/feature/Login*'],
        'payments' => ['tests/unit/Payment*'],
    ],
];

Run Suite:
```
vendor/bin/testo run --suite="auth"
```

Integration Tips

Laravel-Specific Workarounds

Artisan Command Wrapper Create a command to bridge Testo’s CLI to Laravel:

php artisan testo:run --filter="UserTest"

// app/Console/Commands/TestoRunCommand.php
public function handle() {
    $filter = $this->option('filter');
    $command = sprintf('vendor/bin/testo run %s', $filter);
    shell_exec($command);
}

Hybrid Test Runner Use Testo for specific test types (e.g., performance) while keeping Laravel tests in PHPUnit:
```
"scripts": {
  "test": "phpunit",
  "test:performance": "vendor/bin/testo run --type=performance"
}
```

Test Case Isolation

Problem: Testo lacks Laravel’s TestCase traits (e.g., RefreshDatabase).

Solution: Extend Testo’s base test class:

use Testo\TestCase as BaseTestCase;

class LaravelTestCase extends BaseTestCase {
    use RefreshDatabase;
    // Laravel-specific traits
}

Performance Optimization

Parallel Execution: Testo does not natively support parallel testing like PHPUnit. Use CI tools (e.g., GitHub Actions matrix) to split suites:
```
strategy:
  matrix:
    suite: [auth, payments, api]
jobs:
  test:
    run: vendor/bin/testo run --suite="${{ matrix.suite }}"
```

Cache Filter Results: Store filtered test lists in a config file to avoid reprocessing:

// Cache filtered tests for faster subsequent runs
$filteredTests = cache()->remember('testo.filtered', now()->addHours(1), function () {
    return $filter->match($pattern);
});

Gotchas and Tips

Pitfalls

Framework Lock-In
- Issue: Testo is not Laravel-compatible. Mixing Testo and Laravel test helpers (e.g., assertDatabaseHas) will fail.
- Fix: Isolate Testo tests in a separate namespace or project.
CLI Output Incompatibility
- Issue: Testo’s CLI output format differs from Laravel’s phpunit. Custom parsers may be needed for CI tooling (e.g., Slack notifications).
- Fix: Use --format=json and post-process output:
```
vendor/bin/testo run --filter="UserTest" --format=json | jq '.tests'
```
Dataset Filtering Quirks
- Issue: Dataset pointers (@dataset) must match exactly with CLI flags. Typos or missing annotations break filtering.
- Fix: Validate dataset names in tests:
```
// tests/unit/UserTest.php
public function test_premium_user() {
    $this->dataset('users:premium'); // Ensure this matches CLI flag
    // ...
}
```
Path Filtering Edge Cases
- Issue: --path flags use relative paths from the project root. Incorrect paths (e.g., tests/ vs. ./tests) cause no tests to run.
- Fix: Use absolute paths or verify with:
```
vendor/bin/testo run --path="tests/unit" --list
```
No Native IDE Support
- Issue: Testo lacks IDE plugins (e.g., VS Code Test Adapter). Running tests via CLI is manual.
- Fix: Use a custom task runner (e.g., npm-run-all) to wrap Testo commands.

Debugging

Dry Run Mode Use --list to preview matched tests without execution:
```
vendor/bin/testo run --filter="UserTest" --list
```
Verbose Logging Enable debug output for filter parsing:
```
vendor/bin/testo run --filter="UserTest" -vv
```

Testo Configuration Override default filter behavior in testo.php:

return [
    'filter' => [
        'strict' => false, // Allow partial name matches
        'ignore_case' => true,
    ],
];

Extension Points

Custom Filter Rules Extend the Filter class to add logic (e.g., filter by test tags):

namespace App\Extensions;

use Testo\Filter\Filter as BaseFilter;

class TagFilter extends BaseFilter {
    public function matchByTag(string $tag): array {
        return $this->tests->filter(fn ($test) => str_contains($test->getAnnotation('tag'), $tag));
    }
}

Pre-Process Filters Hook into Testo’s event system to modify filters dynamically:

Testo::listen('filtering', function ($event) {
    if (app()->environment('local')) {
        $event->addFilter('UserTest'); // Auto-add filter in local env
    }
});

CI-Specific Filters Use environment variables to dynamically set filters:

FILTER_PATTERN=LoginTest vendor/bin/testo run --filter="$FILTER_PATTERN"

// In a service provider
$filter

Filter Laravel Package