Ftg Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies

   composer require benblub/ftg "dev-main" zenstruck/foundry
   

2. Configure Bundles Add to config/bundles.php:

   Benblub\Ftg\BenblubFtgBundle::class => ['dev' => true],
   

3. Register Maker Command Add to config/services.yaml:

   Benblub\Ftg\Bundle\Maker\MakeFunctionalTest:
       tags: ['maker.command']
   

4. Generate a Factory

   php bin/console make:factory User --test
   

   Define myDefaults() in your factory (e.g., UserFactory.php):

   public static function myDefaults(): array
   {
       return (new self())->getDefaults();
   }
   

5. First Test Generation

   php bin/console make:ftg:test User
   

   This creates a test class extending ApiTestCase with basic CRUD operations.

Implementation Patterns

Workflow: Test-Driven Development with FTG

1. Define Factory First Ensure factories exist for all tested entities. Use --test flag for test-specific factories.

   php bin/console make:factory Post --test
   

2. Generate Test Skeleton

   php bin/console make:ftg:test Post
   

   Outputs a test class (e.g., PostFunctionalTest) with:

   • Setup/teardown methods.
   • Factory instantiation.
   • Basic assertions for CRUD operations.

3. Extend Test Logic Manually add custom assertions or edge cases:

   public function testCustomValidation(): void
   {
       $post = $this->createPost(['title' => '']); // Missing title
       $this->assertResponseStatusCode(400);
   }
   

4. Authentication Integration Implement AuthHelperInterface in a custom helper (e.g., CustomAuthHelper):

   class CustomAuthHelper extends AuthHelper implements AuthHelperInterface
   {
       public function authenticateAsUser(): void
       {
           // Custom logic (e.g., JWT, OAuth)
       }
   }
   

   Reference it in your test:

   use App\Test\CustomAuthHelper;
   
   class PostFunctionalTest extends ApiTestCase
   {
       use CustomAuthHelper;
   
       public function testAuthenticatedEndpoint(): void
       {
           $this->authenticateAsUser();
           // ...
       }
   }
   

5. Reuse Factories Inject factories via constructor or static methods:

   public function testRelatedEntities(): void
   {
       $user = UserFactory::new()->create();
       $post = PostFactory::new(['user_id' => $user->id])->create();
       // ...
   }
   

Integration Tips

• ApiPlatform Projects: FTG assumes ApiTestCase is available. Ensure api bundle is configured in bundles.php.
• Foundry Factories: Prefer test-specific factories (--test flag) to avoid polluting production factories.
• Custom Assertions: Extend generated tests with PHPUnit assertions or custom helpers.
• CI/CD: Run FTG in pipelines to auto-generate regression tests for new entities.

Gotchas and Tips

Pitfalls

1. Missing Factory Defaults

   • Error: Call to undefined method if myDefaults() is missing.
   • Fix: Always define myDefaults() in test factories:

     public static function myDefaults(): array { return (new self())->getDefaults(); }
     

2. Auth Configuration Not Implemented

   • Issue: custom_auth: true config is referenced but not functional.
   • Workaround: Manually implement AuthHelperInterface and bypass config.

3. Bundle Autoloading

   • Error: Class not found for BenblubFtgBundle.
   • Fix: Ensure config/bundles.php includes the bundle before running commands.

4. Foundry Dependency

   • Error: FTG fails if Foundry factories are missing.
   • Fix: Generate factories first (make:factory --test).

5. Test Isolation

   • Risk: Shared test data between tests may cause flakiness.
   • Tip: Use Foundry’s create() (persists) vs. new() (in-memory) judiciously.

Debugging

• Command Output: Run with -v for verbose logs:

  php bin/console make:ftg:test User -v
  

• Factory Debugging: Dump defaults:

  var_dump(UserFactory::myDefaults());
  

• API Responses: Inspect raw responses:

  $response = $this->client->request('GET', '/api/posts');
  $this->assertJson($response->getContent());
  

Extension Points

1. Custom Test Templates Override the default test template by publishing and modifying:

   php bin/console make:ftg:resources
   

   Edit templates/test/TestFunctionalTest.txt.twig.

2. Dynamic Factory States Extend factories to support dynamic states (e.g., withPublishedStatus()):

   public function withPublishedStatus(): static
   {
       return $this->state([...]);
   }
   

3. Hooks for Pre/Post Test Actions Use PHPUnit’s @before/@after annotations or trait methods:

   trait TestSetup
   {
       protected function setupDatabase(): void { /* ... */ }
   }
   

4. Parallel Testing FTG tests are PHPUnit-compatible. Use --parallel flag:

   phpunit -c phpunit.xml.dist --testdox-html report.html --parallel