Eris Laravel Package

Technical Evaluation

Architecture Fit

• Property-Based Testing (PBT) Paradigm: Eris aligns well with modern PHP testing practices by introducing PBT, which is a proven methodology for uncovering edge cases and invariants. This complements traditional unit testing (e.g., PHPUnit) by shifting focus from example-based to property-based validation.
• Laravel Ecosystem Synergy: Laravel’s testing stack (PHPUnit, Pest) can seamlessly integrate Eris, especially for validating business logic, data transformations, or API contracts where edge cases are critical (e.g., payment processing, data serialization).
• Complementarity with Existing Tools:
  • Pest: If using Pest, Eris can be integrated via PHPUnit’s test runner, though Pest’s fluent syntax may require minor adjustments.
  • Laravel Factories: Eris generators can replace or augment Laravel’s Model::factory() for generating complex, randomized test data (e.g., nested relationships, edge-case timestamps).
  • API Testing: Ideal for validating HTTP responses against properties (e.g., "all status codes in 2xx range must include a success field").

Integration Feasibility

• Low Friction: Eris is designed as a drop-in PHPUnit extension with minimal boilerplate. The TestTrait and Generators classes require only:

  use Eris\TestTrait;
  use Eris\Generators;
  

  • No Laravel-Specific Dependencies: Works agnostically of Laravel’s service container or ORM.
  • Composer Integration: Zero configuration beyond composer require --dev giorgiosironi/eris.
• Generator Flexibility: Supports primitive types (int, string, bool), collections (arrays, DateTime), and custom objects via suchThat or bind. Example:

  $this->forAll(
      Generators::tuple(
          Generators::string()->minLength(5),
          Generators::choose(1, 100)
      )
  )->then(fn([$name, $age]) => $this->assertTrue($age > 18 || strlen($name) > 10));
  

• Shrinking: Automatically reduces failing inputs to minimal reproducible cases, improving debugging efficiency.

Technical Risk

• Learning Curve: PBT requires a mindset shift from example-based testing. Teams accustomed to PHPUnit assertions may need training to leverage Eris effectively.
  • Mitigation: Start with simple properties (e.g., "all user emails must be valid") and gradually adopt complex generators.
• Performance Overhead: Generating large test suites may slow down CI pipelines. Eris includes limitTo() and duration() to control test execution time.
  • Mitigation: Use sample() for quick validation or run Eris tests in parallel with PHPUnit’s --parallel flag.
• False Positives/Negatives: Shrinking may not always find the "simplest" failing case, or properties might be too loose/strict.
  • Mitigation: Combine with traditional unit tests and use suchThat() to constrain generators tightly.
• Laravel-Specific Edge Cases:
  • Database Transactions: Eris tests may need @database or RefreshDatabase traits to avoid polluting test data.
  • Service Providers: If testing providers, ensure generators don’t leak state (e.g., use Generators::constant() for singletons).

Key Questions

1. Adoption Strategy:
   • Should Eris replace existing factories (e.g., Laravel’s Model::factory()) or augment them?
   • How will the team balance PBT (Eris) with traditional unit tests (PHPUnit/Pest)?
2. CI/CD Impact:
   • Will Eris tests run in the same pipeline as unit tests, or in a separate "property validation" stage?
   • How will flaky PBT results (e.g., non-deterministic shrinking) be handled?
3. Tooling Integration:
   • Can Eris integrate with Laravel’s phpunit.xml configuration (e.g., grouping tests)?
   • Will Pest’s test listeners need customization to support Eris?
4. Maintenance:
   • How will the team document Eris properties alongside traditional tests?
   • Who will own the "canonical" set of properties for critical modules?

Integration Approach

Stack Fit

• PHPUnit/Pest Compatibility: Eris is designed for PHPUnit but works with Pest via its underlying test runner. Key considerations:
  • Pest: Use uses(TestTrait::class) in test files or extend a base test class.
  • PHPUnit: Native support with zero configuration.
• Laravel Testing Stack:
  • Database Testing: Pair with RefreshDatabase or @database traits to avoid side effects.
  • HTTP Testing: Use Generators::json() or Generators::xml() for API payloads.
  • Queues/Jobs: Test job payloads with Generators::array() or custom objects.
• Type Systems:
  • PHP 8.1+ Attributes: Eris annotations (e.g., @eris-repeat) may conflict with Laravel’s #[Test] or #[Assert] attributes. Prefer programmatic configuration.

Migration Path

1. Pilot Phase:
   • Start with 1–2 critical modules (e.g., payment validation, data serialization).
   • Replace 1–2 example-based tests with Eris properties (e.g., "all order totals must be positive").
   • Example migration:

     // Before (PHPUnit)
     public function testOrderTotalIsPositive() {
         $order = Order::factory()->create(['total' => 100]);
         $this->assertGreaterThan(0, $order->total);
     }
     // After (Eris)
     public function testOrderTotalIsAlwaysPositive() {
         $this->forAll(Generators::choose(1, 1_000_000))
             ->then(fn($total) => $this->assertGreaterThan(0, $total));
     }
     

2. Incremental Adoption:
   • Phase 1: Replace factories with Eris generators for test data.
   • Phase 2: Add properties to existing test suites (e.g., "all user emails must be unique").
   • Phase 3: Introduce Eris for API contract testing (e.g., "all 2xx responses must include a meta field").
3. Tooling Setup:
   • Add to composer.json:

     "require-dev": {
         "giorgiosironi/eris": "^1.0"
     }
     

   • Update phpunit.xml to include Eris-specific configurations:

     <php>
         <env name="ERIS_SEED" value="12345"/> <!-- For reproducibility -->
     </php>
     

Compatibility

• PHP Versions: Laravel 10+ (PHP 8.1+) is fully supported. Laravel 9 (PHP 8.0) may require Eris ~0.14.
• PHPUnit Versions: Laravel’s default PHPUnit 10/11/12/13 are all compatible.
• Laravel-Specific Conflicts:
  • Service Container: Avoid binding generators to the container (use Generators::constant() for singletons).
  • Test Traits: Prefer TestTrait over Laravel’s RefreshDatabase in the same class to avoid method conflicts.
  • Annotations: Eris annotations (e.g., @eris-repeat) may clash with Laravel’s #[Test] or #[Assert]. Use programmatic configuration:

    $this->forAll(Generators::string())
        ->repeat(100) // Instead of @eris-repeat
        ->then(...);
    

Sequencing

1. Pre-Integration:
   • Audit existing tests for edge cases not covered by examples.
   • Document critical invariants (e.g., "all timestamps must be UTC").
2. Integration:
   • Add Eris to composer.json and run composer update.
   • Write 1–2 Eris properties per module alongside existing tests.
3. Validation:
   • Run Eris tests in CI with --stop-on-failure to catch regressions.
   • Compare coverage with traditional tests (e.g., "Does Eris find cases PHPUnit misses?").
4. Optimization:
   • Tune generator sizes (limitTo()) to balance coverage and performance.
   • Use sample() for quick validation in development.

Operational Impact

Maintenance

• Test Documentation:
  • Eris properties should be documented alongside traditional tests (e.g., in README.md or a PROPERTIES.md file).
  • Example:

    ## Order Properties
    - All order totals must be positive (Eris: `testOrderTotalIsAlwaysPositive`).
    - All line items must have a valid product ID (Eris: `testLineItemProductIdExists`).
    

• Generator Updates:
  • Custom generators (e.g., for domain-specific objects) may need updates if the domain model changes.
  • Mitigation: Use suchThat() to constrain generators to stable interfaces.
• Deprecation: