Codeception Module Robo Task Runner Laravel Package

Getting Started

Minimal Setup

1. Installation Add the module via Composer in your Laravel project:

   composer require --dev sweetchuck/codeception-module-robo-task-runner
   

2. Configure Codeception In your codeception.yml, register the module under the modules section:

   modules:
       config:
           RoboTaskRunner:
               tasks: ['@app/console', 'your:robo-task']
   

3. First Use Case In a Codeception test (e.g., acceptance.suite.yml or a custom test file), use the module to execute a Robo task:

   <?php
   $I = new AcceptanceTester($scenario);
   $I->runRoboTask('your:robo-task', ['--option' => 'value']);
   

Implementation Patterns

Workflows

1. Task Execution in Tests Use the module to trigger Robo tasks during test suites (e.g., setup/teardown, data migration, or environment prep):

   $I->runRoboTask('migrate:fresh', ['--seed' => true]);
   

2. Parameterized Task Calls Pass dynamic arguments to Robo tasks:

   $I->runRoboTask('generate:model', ['name' => 'User', '--force' => true]);
   

3. Integration with Codeception Hooks Hook into suiteBefore or suiteAfter to run tasks before/after test suites:

   suites:
       acceptance:
           actors: AcceptanceTester
           modules:
               enabled: [RoboTaskRunner]
           _before:
               - runRoboTask: ['setup:environment']
           _after:
               - runRoboTask: ['teardown:environment']
   

4. Conditional Task Execution Use Codeception’s conditional logic to run tasks based on test scenarios:

   if ($I->grabEnvironment('ENVIRONMENT') === 'staging') {
       $I->runRoboTask('deploy:staging');
   }
   

Integration Tips

• Laravel-Specific Tasks Ensure your Robo tasks are autoloaded (e.g., via RoboFile.php in app/Console). Example:

  // app/Console/RoboFile.php
  class RoboFile extends \Robo\Tasks
  {
      public function deployStaging()
      {
          // Task logic
      }
  }
  

• Task Discovery Use @app/console to dynamically resolve the RoboFile path in codeception.yml:

  modules:
      config:
          RoboTaskRunner:
              tasks: ['@app/console']
  

• Output Handling Redirect task output to Codeception’s logger for visibility:

  $I->runRoboTask('log:clear', [], ['output' => true]);
  

Gotchas and Tips

Pitfalls

1. Task Not Found

   • Cause: Incorrect task name or path in codeception.yml.
   • Fix: Verify the task exists in RoboFile.php and use the exact method name (e.g., deploy:staging maps to deployStaging()).

2. Dependency Conflicts

   • Cause: Version mismatches between codeception/codeception, consolidation/robo, or this module.
   • Fix: Pin versions in composer.json:

     "require-dev": {
         "codeception/codeception": "^4.2",
         "consolidation/robo": "^1.4",
         "sweetchuck/codeception-module-robo-task-runner": "^4.0"
     }
     

3. Environment Isolation

   • Cause: Robo tasks may rely on global state (e.g., Laravel’s service container).
   • Fix: Reset the container or use --env=testing in task arguments:

     $I->runRoboTask('migrate', [], ['--env' => 'testing']);
     

4. Output Pollution

   • Cause: Task output (e.g., logs) cluttering Codeception’s test output.
   • Fix: Suppress output or redirect to a file:

     $I->runRoboTask('log:clear', [], ['output' => false]);
     

Debugging

• Enable Verbose Mode Add --verbose to task arguments to debug:

  $I->runRoboTask('your:task', [], ['--verbose' => true]);
  

• Check Task Arguments Use print_r or var_dump in RoboFile.php to inspect passed arguments:

  public function yourTask($args)
  {
      var_dump($args); // Debug input
  }
  

Extension Points

1. Custom Task Arguments Extend the module by overriding runRoboTask in a custom helper:

   // tests/_support/Helper/Acceptance.php
   class AcceptanceHelper extends \Codeception\Module
   {
       public function runCustomTask($task, $args = [], $options = [])
       {
           $this->_runRoboTask($task, $args, $options);
       }
   }
   

2. Pre/Post Task Hooks Add logic before/after task execution via Codeception events:

   // In a custom module
   public function _beforeRunRoboTask()
   {
       // Pre-task logic
   }
   
   public function _afterRunRoboTask()
   {
       // Post-task logic
   }
   

3. Dynamic Task Loading Load tasks dynamically based on test environment:

   modules:
       config:
           RoboTaskRunner:
               tasks: ['@app/console', '%env(ROBO_TASK)%']
   

   Then set ROBO_TASK in your test environment.

Config Quirks

• Path Resolution The @app/console placeholder resolves to app/Console/RoboFile.php. For custom paths, use absolute paths:

  tasks: ['/absolute/path/to/RoboFile.php']
  

• Task Aliases Define aliases in RoboFile.php for cleaner test calls:

  // app/Console/RoboFile.php
  public function taskAlias()
  {
      $this->taskYourTask();
  }
  

  Then call taskAlias in tests.