Atoum Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require-dev atoum/atoum-bundle
   

   Add to config/bundles.php (Symfony 7+):

   atoum\AtoumBundle\AtoumAtoumBundle::class => ['dev' => true, 'test' => true],
   

2. First Test: Create a test class extending atoum\AtoumBundle\Test\Units\Test:

   // tests/Unit/MyTest.php
   namespace Tests\Unit;
   use atoum\AtoumBundle\Test\Units\Test;
   
   class MyTest extends Test {
       public function testExample() {
           $this->boolean(true)->isTrue();
       }
   }
   

3. Run Tests:

   php bin/console atoum --directory=tests/Unit
   

Key First Use Cases

• Unit Testing: Extend Test for simple assertions.
• Web Tests: Use WebTestCase for HTTP requests.
• Command Testing: Extend CommandTestCase for CLI commands.
• Form Testing: Use FormTestCase for Symfony forms.

Implementation Patterns

1. Test Class Structure

• Base Classes:

  • Test: For unit tests (e.g., services, entities).
  • WebTestCase: For HTTP/Controller tests (extends Test).
  • CommandTestCase: For Symfony commands.
  • FormTestCase: For Symfony forms.

• Example Workflow:

  // tests/Unit/Service/MyServiceTest.php
  class MyServiceTest extends Test {
      public function testServiceMethod() {
          $service = $this->getService('my_service');
          $result = $service->doSomething();
          $this->string($result)->isEqualTo('expected');
      }
  }
  

2. Configuration-Driven Testing

• Define test directories in config/packages/test/atoum.yaml:

  atoum:
      bundles:
          AppBundle:
              directories: [Tests/Unit, Tests/Functional]
  

• Run via CLI:

  php bin/console atoum AppBundle
  

3. Faker Integration

• Generate fake data in tests:

  public function testWithFakeData() {
      $fakeName = $this->faker->name;
      $this->string($fakeName)->isNotEmpty();
  }
  

4. Web Testing Patterns

• Controller Tests:

  class MyControllerTest extends ControllerTest {
      public function testGetAction() {
          $this->request()->GET('/endpoint')->hasStatus(200);
      }
  }
  

• Kernel Initialization: Override getKernelDirectory() if Symfony can't auto-detect:

  class MyWebTest extends WebTestCase {
      protected function getKernelDirectory() {
          return __DIR__ . '/../../../../var/cache/dev';
      }
  }
  

5. Command Testing

• Test CLI commands with CommandTestCase:

  class MyCommandTest extends CommandTestCase {
      public function testExecute() {
          $command = new MyCommand();
          $commandTester = $this->createCommandTester($command);
          $exitCode = $commandTester->execute([]);
          $this->integer($exitCode)->isEqualTo(0);
      }
  }
  

6. Reporting

• Generate reports (XUnit/Clover) via CLI:

  php bin/console atoum --directory=tests --report=xunit
  

Gotchas and Tips

Common Pitfalls

1. Kernel Initialization Issues:

   • Symptom: No kernel found or AppKernel not found.
   • Fix: Override getKernelDirectory() in your test class or ensure APP_KERNEL_DIR is set in .env.test.

2. Directory Configuration:

   • Symptom: Tests not discovered.
   • Fix: Use --directory flag for Symfony 7+:

     php bin/console atoum --directory=tests/Unit --directory=tests/Integration
     

3. Faker Not Available:

   • Symptom: $this->faker throws UndefinedPropertyException.
   • Fix: Ensure fakerphp/faker is installed (composer require-dev fakerphp/faker).

4. Exit Codes:

   • Symptom: CLI returns non-zero even with passing tests.
   • Fix: Use --debug to inspect underlying atoum output:

     php bin/console atoum --debug
     

Debugging Tips

• Verbose Output:

  php bin/console atoum --verbose
  

• Light Report:

  php bin/console atoum --light-report
  

• Loop Mode (for iterative testing):

  php bin/console atoum --loop
  

Extension Points

1. Custom Test Classes: Extend base classes to add pre/post hooks:

   class CustomTest extends Test {
       protected function beforeTestMethod($method) {
           $this->mock('service')->get('mocked');
       }
   }
   

2. Atoum Configuration: Pass atoum-specific options via CLI:

   php bin/console atoum --directory=tests --filter="testMethod"
   

3. Symfony Services: Access services in tests via $this->getService('service_id').

Configuration Quirks

• Bundle Aliases: Use full bundle names (e.g., AcmeFooBundle) in atoum.yaml, not aliases.
• PHP 8.1+: Ensure your composer.json enforces PHP 8.1+ for AtoumBundle 3.0+.
• PSR-4 Autoloading: AtoumBundle 3.0+ uses PSR-4; ensure your composer.json autoloads correctly.

Performance Tips

• Skip Kernel Boot: Use @noResetKernel annotation for fast unit tests:

  /**
   * @noResetKernel
   */
  class FastUnitTest extends Test { ... }
  

• Parallel Testing: Atoum supports parallel execution; combine with Symfony’s parallel-lint or custom scripts.

Migration Notes (2.x → 3.0)

• Symfony 7+: AtoumBundle 3.0 drops Symfony 6 support.
• PSR-4: Update autoloading in composer.json:

  "autoload": {
      "psr-4": { "Tests\\": "tests/" }
  }
  

• Command Changes: Replace ContainerAwareCommand with dependency-injected Command.
• Type Safety: Add return types to custom test methods for full compatibility.