Ci Scripts Laravel Package

Getting Started

Minimal Steps

1. Installation: Install via Composer or clone the repository and integrate into your Ibexa DXP CI workflow:

   composer require ibexa/ci-scripts --dev
   

   Or clone directly:

   git clone https://github.com/ibexa/ci-scripts.git
   

2. First Use Case: Run a basic Ibexa DXP installation with improved CLI feedback and visual testing:

   ./ci-scripts/bin/install.sh --edition=COMMUNITY --php-version=8.2 --visual
   

   This installs Ibexa DXP with colored output, visual regression testing, and separated search indexing.

3. Key Files to Review:

   • bin/install.sh: Updated with CLI edition passing and colored output.
   • config/recipes/: New visual testing configurations (e.g., visual-testing.yml).
   • tests/: Expanded test suite including Ibexa Headless regression tests.
   • bin/test.sh: Supports --visual flag for visual regression testing.

Implementation Patterns

Usage Patterns

1. CI Pipeline Integration: Updated scripts now support colored output and visual testing. Example GitHub Actions workflow:

   - name: Install Ibexa DXP with Visual Testing
     run: ./ci-scripts/bin/install.sh --edition=ENTERPRISE --visual
   

   • New Flags:
     • --visual: Enables visual regression testing (requires ibexa/behat).
     • --php-version: Now defaults to 8.1 (minimum) or 8.2 (recommended).
     • --edition: Passed directly from CLI (no hardcoded productVersion logic).

2. Visual Testing: Leverage the built-in visual regression testing with improved Behat integration:

   ./ci-scripts/bin/test.sh --visual --recipe=visual-testing.yml
   

   Requires ibexa/behat and a configured tool (e.g., Percy). Skip with --no-visual.

3. Recipe Customization: Extend recipes with visual testing or Node.js/PHP version updates:

   # custom-recipe.yml
   install:
     - composer install
     - nvm install 18
     - ./ci-scripts/bin/test.sh --visual
   

4. Headless Testing: New Ibexa Headless regression tests are included. Run them with:

   ./ci-scripts/bin/test.sh --headless
   

Workflows

• Development Workflow: Use --reset and --visual for local testing with visual feedback:

  ./ci-scripts/bin/install.sh --edition=COMMUNITY --reset --visual
  

• Release Workflow: Updated release script handles fresh Behat tags and PHP 8.2 error handling:

  ./ci-scripts/bin/release.sh --version=4.6.0 --php-version=8.2
  

Integration Tips

• Docker Integration: Scripts now move ibexa/docker installation to the end of the phase for better dependency resolution.
• PHP/Node.js Updates: Default Node.js version is now 18, and PHP 8.1+ is required (8.2 recommended).
• Composer Workflow: Scripts now run composer install for PHP ≥8.1 and composer update otherwise (configurable via recipes).
• Edition Handling: Editions are passed directly from CLI (no hardcoded logic). Override with --force if needed.

Gotchas and Tips

Pitfalls

1. PHPUnit Version Conflicts: Temporary PHPUnit 9 pinning was reverted in v0.2.4. Ensure your phpunit.xml aligns with project defaults.
2. Visual Testing Dependencies: Visual testing requires ibexa/behat and a screenshot tool (e.g., Percy). Skip with --no-visual if not needed.
3. Git Safe Directory: /var/www is now marked as a safe Git directory by default. To revert:

   git config --global --remove-safe-directory /var/www
   

4. PHP 8.2 Error Handling: The script adds a custom error handler for PHP 8.2. Disable it in php.ini if conflicts arise:

   error_handler=
   

5. Hardcoded Paths: Avoid modifying /var/www directly. Use --reset to clean it if needed.

Debugging

• Verbose Output: Add -v to scripts for detailed logs (now with colored output):

  ./ci-scripts/bin/install.sh -v --edition=COMMUNITY --visual
  

• Recipe Testing: Test recipes locally with:

  ./ci-scripts/bin/test.sh --recipe=custom-recipe.yml --visual
  

• Database/Search Issues: Search indexing is now separated from DB installation. Override the install phase in recipes if needed:

  install:
    - ./ci-scripts/bin/install.sh --edition=COMMUNITY --no-search
  

Config Quirks

1. Edition Exclusions: Higher editions (e.g., ENTERPRISE) automatically exclude lower-edition packages. Override with --force.
2. Node.js/PHP Version Bumps: Default Node.js is now 18, and PHP 8.1+ is required. Update your recipes if using older versions.
3. Visual Testing Tools: Replace the default tool by overriding the visual-testing step in recipes. Example:

   visual-testing:
     - ./vendor/bin/percy exec -- npm run test:visual
   

4. Dependency Execution: Recipes for added dependencies now run after the main install. Disable with --no-execute-recipes.

Extension Points

1. Custom Recipes: Add recipes to config/recipes/ and reference them via --recipe=path/to/recipe.yml. Example for visual testing:

   visual-testing:
     - ./ci-scripts/bin/test.sh --visual --tool=percy
   

2. Post-Install Hooks: Extend the install phase to run custom commands (e.g., asset compilation):

   install:
     - ./ci-scripts/bin/install.sh --edition=COMMUNITY
     - npm run build
   

3. Headless Testing: Include Ibexa Headless regression tests in your workflow:

   ./ci-scripts/bin/test.sh --headless
   

4. PHP 8.2 Error Handling: Customize the error handler by extending the install phase in recipes:

   install:
     - ./ci-scripts/bin/install.sh --php-version=8.2
     - echo "error_handler=custom_handler" >> /path/to/php.ini