Add Utility Support

[MrJnrman]

Summary

Enables utility packages to work correctly with the env:up command by processing their requirements (plugins, themes, secrets) and ensuring proper execution timing. This allows developers to use utility packages
for environment configuration during manual testing and development workflows.

Changes

1. Requirement Processing for Utility Packages

• UpEnvironmentCommand.php (lines 296-299): Added call to processTestPackageRequirements() for utility packages
• UpEnvironmentCommand.php (lines 1424-1433, 1480-1489): Extended processTestPackageRequirements() to extract and store secrets
• UpEnvironmentCommand.php (lines 1537-1558): Added secret validation with helpful error messages

2. Secret Handling via EnvironmentManager

• UpEnvironmentCommand.php (lines 664-681): Create and configure EnvironmentManager when secrets are required
• Store EnvironmentManager in App container for cross-component communication
• E2EEnvironment.php (lines 123-127): Retrieve EnvironmentManager from App container and set on orchestrator
• Secrets are now properly passed to Docker container where setup scripts execute

3. Fixed Plugin Activation Timing

• E2EEnvironment.php (lines 79-166): Moved utility package execution from before_plugin_activation() to after_plugin_activation()
• Why: Utility scripts may depend on plugin features (e.g., WooCommerce product post type, payment gateway settings)
• Impact: Only affects env:up; run:e2e unaffected (uses skip_test_phases flag)

4. Validation for Utility Packages

• UpEnvironmentCommand.php (lines 591-617): Reject packages with run phase in utilities array
• RunE2ECommand.php (lines 360-391): Same validation for run:e2e
• Clear error messages explain how to fix the issue

5. Context-Aware Output Messaging

• E2EEnvironment.php (lines 110-117): Shows "Running Package Setup (--global-setup mode)" vs "Running Test Package Setup"
• Provides clarity about what's executing

Testing Instructions

Test 1: Basic Utility Package with Required Plugins

Setup: Create a test utility package
mkdir -p test-utilities/plugin-config

  cat > test-utilities/plugin-config/qit-test.json << 'EOF'
  {
    "$schema": "https://qit.woo.com/json-schema/test-package",
    "package": "test/plugin-config",
    "test_type": "e2e",
    "description": "Configure plugin settings",
    "requires": {
      "plugins": ["woocommerce"]
    },
    "test": {
      "phases": {
        "globalSetup": [
          "wp option set my_plugin_setting 'configured'",
          "wp user create testuser [email protected] --role=editor --user_pass=password123"
        ]
      }
    }
  }
  EOF

Test:

Create qit.json with utility

  cat > qit.json << 'EOF'
  {
    "$schema": "https://qit.woo.com/json-schema/qit",
    "environments": {
      "test": {
        "php": "8.2",
        "wp": "latest",
        "utilities": ["./test-utilities/plugin-config"]
      }
    }
  }
  EOF

Start environment

  php src/qit-cli.php env:up --environment=test

Expected:

• ✅ Required plugins are installed and activated
• ✅ WordPress options are set correctly
• ✅ Test user is created
• ✅ Environment starts without errors

Test 2: Utility Package with Secrets

Setup:

  mkdir -p test-utilities/api-config
  cat > test-utilities/api-config/qit-test.json << 'EOF'
  {
    "$schema": "https://qit.woo.com/json-schema/test-package",
    "package": "test/api-config",
    "test_type": "e2e",
    "requires": {
      "secrets": ["API_KEY", "API_SECRET", "WEBHOOK_URL"]
    },
    "test": {
      "phases": {
        "globalSetup": ["./configure-api.sh"]
      }
    }
  }
  EOF

  cat > test-utilities/api-config/configure-api.sh << 'EOF'
  #!/bin/bash
  set -e
  echo "Configuring API with credentials..."
  wp option set my_api_key "${API_KEY}"
  wp option set my_api_secret "${API_SECRET}"
  wp option set my_webhook_url "${WEBHOOK_URL}"
  echo "API configured successfully"
  EOF
  chmod +x test-utilities/api-config/configure-api.sh

  Test with secrets:
  export API_KEY='test-key-12345'
  export API_SECRET='secret-xyz-789'
  export WEBHOOK_URL='https://example.com/webhook'

  php src/qit-cli.php env:up --environment=test --utility=./test-utilities/api-config

Expected:

• ✅ Secrets are accessible in setup script
• ✅ WordPress options are set with secret values
• ✅ No "missing secret" errors
• ✅ Setup script completes successfully

Test without secrets:

  unset API_KEY API_SECRET WEBHOOK_URL

  php src/qit-cli.php env:up --environment=test --utility=./test-utilities/api-config

Expected:

• ❌ Clear error message: "Missing required secrets:"
• ❌ Lists each missing secret (API_KEY, API_SECRET, WEBHOOK_URL)
• ❌ Shows example: export API_KEY='your-secret-value'
• ❌ Environment does not start

Test 3: Validation - Reject Test Packages as Utilities

Setup:

  mkdir -p test-utilities/invalid-utility
  cat > test-utilities/invalid-utility/qit-test.json << 'EOF'
  {
    "$schema": "https://qit.woo.com/json-schema/test-package",
    "package": "test/invalid-utility",
    "test_type": "e2e",
    "test": {
      "phases": {
        "globalSetup": ["echo 'Setting up...'"],
        "run": ["npx playwright test"]
      }
    }
  }
  EOF

Test:

  php src/qit-cli.php env:up --environment=test --utility=./test-utilities/invalid-utility

Expected:

• ❌ Error: "Validation Error: Packages in 'utilities' or 'global_setup' must NOT have a 'run' phase."
• ❌ Lists the invalid package: test/invalid-utility
• ❌ Provides fix options:
  • Remove the 'run' phase to make it a utility, OR
  • Move to 'test_packages' array, OR
  • Remove from 'utilities' array
• ❌ Environment does not start

Test 4: Timing - Plugin-Dependent Operations

Setup:

  mkdir -p test-utilities/create-content
  cat > test-utilities/create-content/qit-test.json << 'EOF'
  {
    "$schema": "https://qit.woo.com/json-schema/test-package",
    "package": "test/create-content",
    "test_type": "e2e",
    "requires": {
      "plugins": ["woocommerce"]
    },
    "test": {
      "phases": {
        "globalSetup": [
          "wp post create --post_type=product --post_title='Test Product' --post_status=publish",
          "wp post list --post_type=product --format=count"
        ]
      }
    }
  }
  EOF

Test:

  php src/qit-cli.php env:up --environment=test --utility=./test-utilities/create-content

Expected:

• ✅ No "Invalid post type product" errors
• ✅ Custom post type content created successfully
• ✅ Post count displayed correctly
• ✅ Utility runs AFTER required plugins are activated

Note: This test demonstrates that utilities now run after plugin activation, allowing them to use plugin-registered post types, taxonomies, and other features.

Test 5: --global-setup Flag

Test:

Create environment with multiple utilities

  cat > qit.json << 'EOF'
  {
    "$schema": "https://qit.woo.com/json-schema/qit",
    "environments": {
      "dev": {
        "php": "8.2",
        "wp": "latest",
        "utilities": [
          "./test-utilities/plugin-config",
          "./test-utilities/create-content"
        ]
      }
    }
  }
  EOF

  php src/qit-cli.php env:up --environment=dev --global-setup

Expected:

• ✅ Output shows "Running Package Setup (--global-setup mode)"
• ✅ Runs globalSetup phase for ALL utility packages
• ✅ Runs setup phase for ALL utility packages (not just first)
• ✅ Skips run, teardown, globalTeardown phases
• ✅ Environment stays running for manual testing

Test 6: Multiple Utilities with Mixed Requirements

Setup:

Utility 1: Disable onboarding

  mkdir -p test-utilities/disable-onboarding
  cat > test-utilities/disable-onboarding/qit-test.json << 'EOF'
  {
    "$schema": "https://qit.woo.com/json-schema/test-package",
    "package": "test/disable-onboarding",
    "test_type": "e2e",
    "test": {
      "phases": {
        "globalSetup": [
          "wp option set show_welcome_screen 0",
          "wp option set onboarding_completed true"
        ]
      }
    }
  }
  EOF

Utility 2: Seed test data

  mkdir -p test-utilities/seed-data
  cat > test-utilities/seed-data/qit-test.json << 'EOF'
  {
    "$schema": "https://qit.woo.com/json-schema/test-package",
    "package": "test/seed-data",
    "test_type": "e2e",
    "requires": {
      "plugins": ["woocommerce"]
    },
    "test": {
      "phases": {
        "globalSetup": [
          "wp user create customer [email protected] --role=customer --user_pass=test123",
          "wp post create --post_type=product --post_title='Sample Product' --post_status=publish"
        ]
      }
    }
  }
  EOF

  cat > qit.json << 'EOF'
  {
    "$schema": "https://qit.woo.com/json-schema/qit",
    "environments": {
      "full": {
        "php": "8.2",
        "wp": "latest",
        "woo": "latest",
        "utilities": [
          "./test-utilities/disable-onboarding",
          "./test-utilities/seed-data"
        ]
      }
    }
  }
  EOF

Test:

  php src/qit-cli.php env:up --environment=full

Expected:

• ✅ WooCommerce plugin installed (from seed-data requirements)
• ✅ Onboarding settings disabled
• ✅ Test customer user created
• ✅ Sample product created
• ✅ All utilities execute in order
• ✅ Environment ready for manual testing

Test 7: Backward Compatibility

Test with qit.json using legacy global_setup field:

  cat > qit.json << 'EOF'
  {
    "$schema": "https://qit.woo.com/json-schema/qit",
    "environments": {
      "legacy": {
        "php": "8.2",
        "wp": "latest",
        "global_setup": ["./test-utilities/plugin-config"]
      }
    }
  }
  EOF

  php src/qit-cli.php env:up --environment=legacy

Expected:

• ✅ Works with legacy global_setup field
• ✅ Utilities execute correctly
• ✅ No breaking changes

Test with run:e2e:
php src/qit-cli.php run:e2e woocommerce
--test-package=./test-utilities/plugin-config

Expected:

• ✅ Works as before
• ✅ No regressions in test execution
• ✅ Secrets handling unchanged