Request Factories Laravel Package

Technical Evaluation

Architecture Fit

• Problem Solved: Addresses a common pain point in Laravel testing—boilerplate-heavy request validation—by abstracting FormRequest validation into reusable factories. This aligns with Laravel’s testing philosophy while reducing test complexity.
• Core Value: Eliminates the need to manually include all validated fields in tests, improving test readability and maintainability. Particularly valuable for APIs with strict validation (e.g., multi-field forms, nested objects).
• Laravel Synergy: Leverages Laravel’s existing testing tools (e.g., Http::fake(), UploadedFile) and integrates seamlessly with Pest/PHPUnit, FormRequests, and routes. No invasive changes to application architecture required.

Integration Feasibility

• Low Friction: Designed as a drop-in package with minimal configuration. Requires only:
  1. Composer installation.
  2. Optional: Custom factory classes for complex validation logic.
• Backward Compatibility: Works with Laravel 9+ (PHP 8.0+). No breaking changes to existing test suites if used selectively.
• Validation Coverage: Supports:
  • Standard FormRequest validation (required, unique, etc.).
  • Custom validation rules (via extends or factory overrides).
  • File uploads (via UploadedFile::fake() integration).
  • Localization (e.g., phone number formats).

Technical Risk

Key Questions

1. Validation Scope:
   • How many FormRequests in the codebase have ≥3 validated fields? (Prioritize high-boilerplate routes first.)
   • Are there dynamic validation rules (e.g., Rule::when()) that factories can’t handle natively?
2. Team Adoption:
   • Will developers prefer factories for new tests, or resist due to learning curve?
   • How will factory updates be communicated (e.g., breaking changes to validation rules)?
3. CI/CD Impact:
   • Will factory tests replace or augment existing test suites? (Avoid redundancy.)
   • Are there performance bottlenecks in test suites with many factories?
4. Long-Term Maintenance:
   • Who owns factory updates if validation rules change? (Devs or QA?)
   • How will factories be versioned alongside FormRequests?

Integration Approach

Stack Fit

• Primary Use Case: API/HTTP tests in Laravel (Pest/PHPUnit).
• Complementary Tools:
  • Pest: Native support; examples provided.
  • PHPUnit: Requires minor adapter layer (e.g., createRequestFactory() helper).
  • Laravel Dusk: Not directly supported (focuses on browser tests).
  • Feature Tests: Ideal for; Unit Tests: Limited value (factories are HTTP-layer).
• Anti-Patterns:
  • Avoid for database-only tests (e.g., Eloquent model validation).
  • Not a replacement for mocking services in complex workflows.

Migration Path

1. Phase 1: Pilot Routes
   • Select 3–5 high-boilerplate FormRequests (e.g., user registration, payment forms).
   • Refactor tests to use factories; compare test readability and maintenance time.
2. Phase 2: Factory Library
   • Create a shared factory class (e.g., app/Testing/RequestFactories.php) for team-wide reuse.
   • Example:

     use Worksome\RequestFactories\Factories\FormRequestFactory;
     
     $factory = new FormRequestFactory(RegisterUserRequest::class);
     $request = $factory->make(['phone' => '+123']);
     

3. Phase 3: CI Enforcement
   • Add a custom Pest/PHPUnit listener to flag tests that don’t use factories (optional).
   • Enforce factory updates in PR checks (e.g., fail if validation rules change but factories don’t).

Compatibility

Sequencing

1. Pre-Integration:
   • Audit FormRequests for validation complexity (prioritize high-boilerplate routes).
   • Document current test coverage gaps (e.g., missing edge cases).
2. Integration:
   • Start with Pest tests (easiest migration).
   • Gradually convert PHPUnit tests using adapters.
3. Post-Integration:
   • Add factory validation tests to CI (e.g., "Did factories break when rules changed?").
   • Train team on factory best practices (e.g., when to override defaults).

Operational Impact

Maintenance

• Pros:
  • Reduced test flakiness: Factories centralize validation logic, reducing "works on my machine" issues.
  • Easier refactoring: Change validation rules in one place (FormRequest) and update factories.
• Cons:
  • Factory drift risk: If FormRequests change but factories aren’t updated, tests may pass falsely.
  • Overhead for simple tests: May require opt-out for low-complexity routes.
• Mitigation:
  • Automate factory updates: Use a GitHub Action to sync factories with FormRequests.
  • Document exceptions: Clearly mark tests that must not use factories (e.g., dynamic rules).

Support

• Developer Onboarding:
  • Low barrier: Factories hide complexity; new devs write tests faster.
  • Documentation gap: Package lacks advanced use cases (e.g., nested factories, conditional rules).
• Troubleshooting:
  • Common issues:
    • Factories missing fields → Update factory or add ->ignoreMissing().
    • Validation errors → Check FormRequest rules vs. factory defaults.
  • Debugging tools:
    • Use dd($factory->getValidationRules()) to inspect generated rules.
    • Add Pest/PHPUnit listeners to log factory usage.
• Team Roles:
  • Backend Devs: Own factory updates when validation changes.
  • QA: Focus on test coverage (ensure factories don’t introduce blind spots).

Scaling

• Performance:
  • Minimal impact: Factories add ~5–10ms per test (negligible for most suites).
  • Large suites: Monitor CI times; parallelize tests if bottlenecks arise.
• Team Growth:
  • Scalable: Factories reduce cognitive load for new hires.
  • Consistency: Enforces standardized test patterns across teams.
• Monorepos:
  • Package isolation: Worksome’s package is self-contained; no cross-project conflicts.
  • Shared factories: Can be published as a private package for multi-repo teams.

Failure Modes