Skip to content

testing.md

Latest commit

 

History

History
145 lines (108 loc) · 3.27 KB

testing.md

File metadata and controls

145 lines (108 loc) · 3.27 KB
Raw

Testing Guide for Compose Plugin

This document describes the testing infrastructure for the Compose Manager plugin.

Quick Start

Running PHP Tests (Native)

# Run all PHP unit tests
php vendor/bin/phpunit

# Run with detailed output
php vendor/bin/phpunit --testdox

# Run specific test file
php vendor/bin/phpunit tests/unit/UtilTest.php

# Run with code coverage (requires Xdebug)
php vendor/bin/phpunit --coverage-html tests/coverage/html

Running BATS Tests (Docker)

# Using the helper script
.\run-bats.cmd

# Or directly with Docker
docker run --rm -v "${PWD}:/code" -w /code bats/bats:latest tests/unit/*.bats

VS Code Integration

The workspace is configured with PHPUnit Test Explorer. After opening the project:

  1. Open the Test Explorer panel (beaker icon in sidebar)
  2. Tests will be automatically discovered
  3. Click the play button to run tests
  4. Failed tests show inline in the editor

Test Structure

tests/
├── framework/          # Submodule: plugin-tests framework
│   └── src/
│       ├── php/
│       │   ├── Mocks/      # Function & global mocks
│       │   ├── TestCase.php
│       │   └── bootstrap.php
│       └── bats/
│           └── helpers/    # BATS helper functions
├── unit/
│   ├── UtilTest.php    # PHP unit tests
│   └── compose.bats    # BATS shell tests
├── results/            # JUnit XML output (CI)
└── coverage/           # Code coverage reports

Writing Tests

PHP Tests

<?php
use PluginTests\TestCase;

class MyTest extends TestCase
{
    public function setUp(): void
    {
        parent::setUp();
        // Setup mocks
        $this->mockGlobals(['var' => ['NAME' => 'TestServer']]);
        $this->mockFunction('parse_plugin_cfg', fn() => ['key' => 'value']);
    }

    public function testSomething(): void
    {
        $this->assertEquals('expected', actual_function());
    }
}

BATS Tests

#!/usr/bin/env bats

load '../framework/src/bats/setup.bash'

@test "function returns expected value" {
    result=$(my_function "input")
    assert_equals "expected" "$result"
}

@test "script handles errors" {
    run my_script --invalid-option
    assert_failure
    assert_output_contains "error"
}

CI/CD Integration

The .github/workflows/tests.yml workflow runs on every push and PR:

  • PHP Tests: Runs PHPUnit with coverage
  • BATS Tests: Runs bash tests
  • Static Analysis: Runs PHPStan

Test results appear in the GitHub Actions UI with proper reporting.

Available Mocks

PHP Function Mocks

  • parse_plugin_cfg() - Config parsing
  • autov() - Asset versioning
  • csrf_token() - CSRF protection
  • notify() - Notifications
  • syslog() - Logging

PHP Global Mocks

  • $var - Unraid variables
  • $disks - Disk information
  • $shares - Share data
  • $dockerClient - Docker API

BATS Command Mocks

  • docker / docker-compose - Container operations
  • logger - System logging
  • notify - Unraid notifications
  • File operation helpers

Code Coverage

Generate HTML coverage report:

php vendor/bin/phpunit --coverage-html tests/coverage/html
start tests/coverage/html/index.html

Note: Code coverage requires Xdebug PHP extension.