Consolidate documentation and optimize CI with Composer caching

.github/RUNNING_TESTS.md

@@ -0,0 +1,235 @@
+# Running Tests in InvoicePlane v2
+
+This guide covers how to run tests in InvoicePlane v2, including full test suites, smoke tests, and specific test groups.
+
+## Prerequisites
+
+```bash
+composer install
+cp .env.testing.example .env.testing
+php artisan key:generate --env=testing
+```
+
+## Quick Reference
+
+### Run All Tests
+```bash
+# Using Laravel Artisan (recommended)
+php artisan test
+
+# Using PHPUnit directly
+./vendor/bin/phpunit
+```
+
+### Run Test Suites
+```bash
+# Run only Unit tests
+php artisan test --testsuite=Unit
+
+# Run only Feature tests
+php artisan test --testsuite=Feature
+```
+
+### Run Smoke Tests
+Smoke tests are fast, critical tests that verify core functionality. They use the `#[Group('smoke')]` attribute.
+
+```bash
+# Using PHPUnit with smoke configuration
+php artisan test --configuration=phpunit.smoke.xml
+
+# Using --group flag
+php artisan test --group=smoke
+
+# Run smoke tests for a specific module
+./vendor/bin/phpunit Modules/Clients/Tests/Feature/ --group=smoke
+```
+
+### Run Tests with Coverage
+```bash
+# Generate coverage report
+php artisan test --coverage
+
+# Generate HTML coverage report
+php artisan test --coverage-html coverage/
+
+# View coverage in browser
+open coverage/index.html  # macOS
+xdg-open coverage/index.html  # Linux
+```
+
+## Test Groups
+
+InvoicePlane v2 uses PHPUnit groups to organize tests:
+
+- `smoke` - Fast, critical tests (runs in ~10-30 seconds)
+- `crud` - Create, Read, Update, Delete operation tests
+- `peppol` - Peppol e-invoicing integration tests
+- `integration` - Integration tests with external services
+
+### Run Specific Groups
+```bash
+# Smoke tests only
+php artisan test --group=smoke
+
+# CRUD tests only
+php artisan test --group=crud
+
+# Peppol tests only
+php artisan test --group=peppol
+
+# Multiple groups
+php artisan test --group=smoke,crud
+```
+
+## Module-Specific Tests
+
+### Run Tests for a Specific Module
+```bash
+# All tests for a module
+./vendor/bin/phpunit Modules/Clients/Tests/
+
+# Only Feature tests for a module
+./vendor/bin/phpunit Modules/Clients/Tests/Feature/
+
+# Only Unit tests for a module
+./vendor/bin/phpunit Modules/Clients/Tests/Unit/
+```
+
+### Examples
+```bash
+# Clients module
+./vendor/bin/phpunit Modules/Clients/Tests/
+
+# Invoices module
+./vendor/bin/phpunit Modules/Invoices/Tests/
+
+# Peppol-specific tests
+./vendor/bin/phpunit Modules/Invoices/Tests/Unit/Peppol/
+```
+
+## Individual Test Files
+
+```bash
+# Run a specific test file
+./vendor/bin/phpunit Modules/Clients/Tests/Feature/ContactsTest.php
+
+# Run a specific test method
+./vendor/bin/phpunit --filter it_lists_contacts Modules/Clients/Tests/Feature/ContactsTest.php
+```
+
+## Debugging Tests
+
+### Stop on First Failure
+```bash
+php artisan test --stop-on-failure
+```
+
+### Verbose Output
+```bash
+php artisan test --verbose
+```
+
+### Run with Debug Mode
+```bash
+./vendor/bin/phpunit --debug
+```
+
+### Run Specific Test Method
+```bash
+# Using --filter
+php artisan test --filter it_creates_invoice
+
+# Pattern matching
+php artisan test --filter ".*creates.*"
+```
+
+## Parallel Testing
+
+For faster test execution, ParaTest can be used (if installed in the project):
+
+```bash
+# Run tests in parallel (if ParaTest is available)
+./vendor/bin/paratest
+
+# Run with specific number of processes
+./vendor/bin/paratest --processes=4
+```
+
+**Note:** ParaTest should be added to `composer.json` as a dev dependency if parallel testing is needed:
+
+```bash
+composer require --dev brianium/paratest
+```
+
+## Configuration Files
+
+InvoicePlane v2 uses two PHPUnit configuration files:
+
+- `phpunit.xml` - Default configuration for all tests
+- `phpunit.smoke.xml` - Configuration for smoke tests only
+
+### phpunit.xml
+- Runs all Unit and Feature test suites
+- Uses SQLite in-memory database
+- Includes all test directories
+
+### phpunit.smoke.xml
+- Filters tests by `#[Group('smoke')]` attribute
+- Faster execution (~10-30 seconds)
+- Ideal for CI/CD pipelines and post-deployment checks
+
+## Continuous Integration
+
+### GitHub Actions Workflows
+
+Smoke tests run automatically after Composer dependency updates:
+
+```bash
+# See .github/workflows/composer-update.yml
+```
+
+Full test suite runs manually:
+
+```bash
+# See .github/workflows/phpunit.yml
+```
+
+## Best Practices
+
+1. **Run smoke tests frequently** - They catch critical issues quickly
+2. **Use `--stop-on-failure`** - When debugging to save time
+3. **Run full suite before committing** - Ensure no regressions
+4. **Use coverage reports** - To identify untested code
+5. **Group tests logically** - Use `#[Group()]` for better organization
+
+## Troubleshooting
+
+### Tests Failing Due to Database Issues
+```bash
+# Ensure .env.testing is configured
+cp .env.testing.example .env.testing
+php artisan key:generate --env=testing
+
+# Check database connection
+php artisan test --env=testing
+```
+
+### Memory Limit Issues
+```bash
+# Increase PHP memory limit
+php -d memory_limit=512M artisan test
+```
+
+### Cache Issues
+```bash
+# Clear all caches
+php artisan cache:clear
+php artisan config:clear
+php artisan view:clear
+```
+
+## See Also
+
+- [CONTRIBUTING.md](CONTRIBUTING.md) - Guidelines for contributing tests
+- [TEST_GENERATION_SUMMARY.md](TEST_GENERATION_SUMMARY.md) - Test generation documentation
+- [PEPPOL_TESTS_SUMMARY.md](PEPPOL_TESTS_SUMMARY.md) - Peppol-specific test documentation

.github/actions/setup-php-composer/action.yml

@@ -0,0 +1,57 @@
+name: 'Setup PHP with Composer Caching'
+description: 'Set up PHP environment and install Composer dependencies with intelligent caching'
+inputs:
+  php-version:
+    description: 'PHP version to use'
+    required: false
+    default: '8.2'
+  php-extensions:
+    description: 'PHP extensions to install (comma-separated)'
+    required: false
+    default: 'mbstring, xml, ctype, json, fileinfo, pdo, sqlite, mysql, bcmath'
+  composer-flags:
+    description: 'Flags appended to the composer install command (e.g., --no-dev --optimize-autoloader). Used only when composer-args is empty.'
+    required: false
+    default: '--no-interaction --prefer-dist --optimize-autoloader'
+  composer-args:
+    description: 'Complete argument list passed directly to composer install. When non-empty, this overrides composer-flags and is used as-is.'
+    required: false
+    default: ''
+  working-directory:
+    description: 'Working directory for composer commands'
+    required: false
+    default: '.'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Set up PHP
+      uses: shivammathur/setup-php@v2
+      with:
+        php-version: ${{ inputs.php-version }}
+        extensions: ${{ inputs.php-extensions }}
+        coverage: none
+
+    - name: Get Composer Cache Directory
+      id: composer-cache
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
+
+    - name: Cache Composer dependencies
+      uses: actions/cache@v4
+      with:
+        path: ${{ steps.composer-cache.outputs.dir }}
+        key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
+        restore-keys: |
+          ${{ runner.os }}-composer-
+
+    - name: Install Composer dependencies
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      run: |
+        if [ -n "${{ inputs.composer-args }}" ]; then
+          composer install ${{ inputs.composer-args }}
+        else
+          composer install ${{ inputs.composer-flags }}
+        fi

.github/workflows/README.md

@@ -2,6 +2,37 @@
 
 This directory contains GitHub Actions workflows for automated CI/CD tasks.
 
+## Composite Actions
+
+### Setup PHP with Composer (`.github/actions/setup-php-composer`)
+
+A reusable composite action that sets up PHP and installs Composer dependencies with intelligent caching.
+
+**Benefits:**
+- Reduces Composer install time from 8-12 seconds to 2-4 seconds (with cache hit)
+- Consistent PHP and Composer setup across all workflows
+- Centralized cache management
+
+**Usage:**
+```yaml
+- name: Setup PHP with Composer
+  uses: ./.github/actions/setup-php-composer
+  with:
+    php-version: '8.2'  # Optional, defaults to 8.2
+    php-extensions: 'mbstring, xml, json'  # Optional
+    composer-flags: '--no-dev --optimize-autoloader'  # Optional
+```
+
+**Used by:**
+- `phpunit.yml` - Test execution
+- `phpstan.yml` - Static analysis
+- `pint.yml` - Code formatting
+- `composer-update.yml` - Dependency updates
+- `yarn-update.yml` - Frontend dependency updates
+- `quickstart.yml` - Smoke tests
+
+**Note:** `release.yml` uses manual Composer caching (not this composite action) due to its custom production build flags (`--no-dev`).
+
 ## Available Workflows
 
 ### 1. Production Release (`release.yml`)
@@ -86,14 +117,22 @@ Artifacts are also available in the Actions tab for 90 days.
 **What it does:**
 1. **Runs security audit** - Checks for known vulnerabilities
 2. **Updates dependencies** - Based on selected update type
-3. **Runs tests** - Executes unit tests to verify compatibility
-4. **Runs static analysis** - PHPStan checks for type errors
-5. **Creates pull request** - Automated PR with update details
+3. **Runs smoke tests** - Fast verification after updates (if changes detected)
+4. **Creates pull request** - Automated PR with update details
 
 **Update Types:**
-- `security-only` - Only security fixes (default for scheduled runs)
+- `security-patch` - Security and patch updates (default for scheduled runs)
 - `patch-minor` - Patch and minor version updates
-- `all-dependencies` - All updates including major versions
+- `all-dependencies` - All updates including major versions with `composer bump`
+
+**Smoke Tests:**
+
+After dependencies are updated, the workflow automatically runs smoke tests to verify core functionality:
+- Only runs if `composer.lock` has changes
+- Uses `phpunit.smoke.xml` configuration
+- Executes tests marked with `#[Group('smoke')]`
+- Continues even if tests fail (with `continue-on-error: true`)
+- Typically completes in 10-30 seconds
 
 **Required Secrets:**