[tests] Replace coverage-check dependency (#30)

Author: coisa

.github/workflows/tests.yml

@@ -2,7 +2,19 @@ name: Run PHPUnit Tests
 
 on:
     workflow_call:
+        inputs:
+            min-coverage:
+                description: Minimum line coverage percentage enforced by dev-tools tests.
+                required: false
+                type: number
+                default: 80
     workflow_dispatch:
+        inputs:
+            min-coverage:
+                description: Minimum line coverage percentage enforced by dev-tools tests.
+                required: false
+                type: number
+                default: 80
     pull_request:
     push:
         branches: [ "main" ]
@@ -46,13 +58,16 @@ jobs:
               with:
                   php_version: ${{ matrix.php-version }}
 
+            - name: Resolve minimum coverage
+              id: minimum-coverage
+              run: echo "value=${INPUT_MIN_COVERAGE:-80}" >> "$GITHUB_OUTPUT"
+              env:
+                  INPUT_MIN_COVERAGE: ${{ inputs.min-coverage }}
+
             - name: Run PHPUnit tests
               uses: php-actions/composer@v6
               with:
-                php_version: ${{ matrix.php-version }}
-                php_extensions: pcov pcntl
-                command: 'dev-tools'
-                args: 'tests -- --coverage=public/coverage'
-
-            - name: Ensure minimum code coverage
-              run: php vendor/bin/coverage-check ./public/coverage/clover.xml 80
+                  php_version: ${{ matrix.php-version }}
+                  php_extensions: pcov pcntl
+                  command: 'dev-tools'
+                  args: 'tests -- --coverage=public/coverage --min-coverage=${{ steps.minimum-coverage.outputs.value }}'

composer.json

@@ -30,7 +30,6 @@
         "dg/bypass-finals": "^1.9",
         "ergebnis/composer-normalize": "^2.50",
         "ergebnis/rector-rules": "^1.14",
-        "esi/phpunit-coverage-check": "^3.0",
         "fakerphp/faker": "^1.24",
         "fast-forward/phpdoc-bootstrap-template": "^1.0",
         "friendsofphp/php-cs-fixer": "^3.94",
@@ -47,7 +46,7 @@
         "rector/rector": "^2.3",
         "saggre/phpdocumentor-markdown": "^1.0",
         "shipmonk/composer-dependency-analyser": "^1.8.4",
-        "symfony/console": "^7.3",
+        "symfony/console": "^7.4",
         "symfony/filesystem": "^7.4",
         "symfony/finder": "^7.4",
         "symfony/process": "^7.4",

src/Command/TestsCommand.php

@@ -18,12 +18,19 @@
 
 namespace FastForward\DevTools\Command;
 
+use FastForward\DevTools\PhpUnit\Coverage\CoverageSummaryLoader;
+use FastForward\DevTools\PhpUnit\Coverage\CoverageSummaryLoaderInterface;
+use InvalidArgumentException;
+use RuntimeException;
 use Symfony\Component\Console\Input\InputArgument;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Output\OutputInterface;
+use Symfony\Component\Filesystem\Filesystem;
 use Symfony\Component\Process\Process;
 
+use function is_numeric;
+
 /**
  * Facilitates the execution of the PHPUnit testing framework.
  * This class MUST NOT be overridden and SHALL configure testing parameters dynamically.
@@ -35,6 +42,17 @@ final class TestsCommand extends AbstractCommand
      */
     public const string CONFIG = 'phpunit.xml';
 
+    /**
+     * @param Filesystem|null $filesystem the filesystem utility used for path resolution
+     * @param CoverageSummaryLoaderInterface $coverageSummaryLoader the loader used for `coverage-php` summaries
+     */
+    public function __construct(
+        ?Filesystem $filesystem = null,
+        private readonly CoverageSummaryLoaderInterface $coverageSummaryLoader = new CoverageSummaryLoader(),
+    ) {
+        parent::__construct($filesystem);
+    }
+
     /**
      * Configures the testing command input constraints.
      *
@@ -84,6 +102,11 @@ protected function configure(): void
                 shortcut: 'f',
                 mode: InputOption::VALUE_OPTIONAL,
                 description: 'Filter which tests to run based on a pattern.',
+            )
+            ->addOption(
+                name: 'min-coverage',
+                mode: InputOption::VALUE_REQUIRED,
+                description: 'Minimum line coverage percentage required for a successful run.',
             );
     }
 
@@ -102,6 +125,14 @@ protected function execute(InputInterface $input, OutputInterface $output): int
     {
         $output->writeln('<info>Running PHPUnit tests...</info>');
 
+        try {
+            $minimumCoverage = $this->resolveMinimumCoverage($input);
+        } catch (InvalidArgumentException $exception) {
+            $output->writeln('<error>' . $exception->getMessage() . '</error>');
+
+            return self::FAILURE;
+        }
+
         $arguments = [
             $this->getAbsolutePath('vendor/bin/phpunit'),
             '--configuration=' . parent::getConfigFile(self::CONFIG),
@@ -116,29 +147,21 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             $arguments[] = '--cache-directory=' . $this->resolvePath($input, 'cache-dir');
         }
 
-        if ($input->getOption('coverage')) {
-            $output->writeln(
-                '<info>Generating code coverage reports on path: ' . $this->resolvePath($input, 'coverage') . '</info>'
-            );
-
-            foreach ($this->getPsr4Namespaces() as $path) {
-                $arguments[] = '--coverage-filter=' . $this->getAbsolutePath($path);
-            }
-
-            $arguments[] = '--coverage-text';
-            $arguments[] = '--coverage-html=' . $this->resolvePath($input, 'coverage');
-            $arguments[] = '--testdox-html=' . $this->resolvePath($input, 'coverage') . '/testdox.html';
-            $arguments[] = '--coverage-clover=' . $this->resolvePath($input, 'coverage') . '/clover.xml';
-            $arguments[] = '--coverage-php=' . $this->resolvePath($input, 'coverage') . '/coverage.php';
-        }
+        $coverageReportPath = $this->configureCoverageArguments($input, $arguments, null !== $minimumCoverage);
 
         if ($input->getOption('filter')) {
             $arguments[] = '--filter=' . $input->getOption('filter');
         }
 
         $command = new Process([...$arguments, $input->getArgument('path')]);
 
-        return parent::runProcess($command, $output);
+        $result = parent::runProcess($command, $output);
+
+        if (self::SUCCESS !== $result || null === $minimumCoverage || null === $coverageReportPath) {
+            return $result;
+        }
+
+        return $this->validateMinimumCoverage($coverageReportPath, $minimumCoverage, $output);
     }
 
     /**
@@ -156,4 +179,109 @@ private function resolvePath(InputInterface $input, string $option): string
     {
         return $this->getAbsolutePath($input->getOption($option));
     }
+
+    /**
+     * @param InputInterface $input the raw parameter definitions
+     *
+     * @return float|null the validated minimum coverage percentage, if configured
+     */
+    private function resolveMinimumCoverage(InputInterface $input): ?float
+    {
+        $minimumCoverage = $input->getOption('min-coverage');
+
+        if (null === $minimumCoverage) {
+            return null;
+        }
+
+        if (! is_numeric($minimumCoverage)) {
+            throw new InvalidArgumentException('The --min-coverage option MUST be a numeric percentage.');
+        }
+
+        $minimumCoverage = (float) $minimumCoverage;
+
+        if (0.0 > $minimumCoverage || 100.0 < $minimumCoverage) {
+            throw new InvalidArgumentException('The --min-coverage option MUST be between 0 and 100.');
+        }
+
+        return $minimumCoverage;
+    }
+
+    /**
+     * @param InputInterface $input the raw parameter definitions
+     * @param array<int, string> $arguments the mutable argument list for the PHPUnit process
+     * @param bool $requiresCoverageReport indicates whether a `coverage-php` report is required
+     *
+     * @return string|null the absolute path to the generated `coverage-php` report
+     */
+    private function configureCoverageArguments(
+        InputInterface $input,
+        array &$arguments,
+        bool $requiresCoverageReport,
+    ): ?string {
+        $coverageOption = $input->getOption('coverage');
+
+        if (null === $coverageOption && ! $requiresCoverageReport) {
+            return null;
+        }
+
+        $coveragePath = null !== $coverageOption
+            ? $this->resolvePath($input, 'coverage')
+            : $this->resolvePath($input, 'cache-dir');
+
+        foreach ($this->getPsr4Namespaces() as $path) {
+            $arguments[] = '--coverage-filter=' . $this->getAbsolutePath($path);
+        }
+
+        if (null !== $coverageOption) {
+            $arguments[] = '--coverage-text';
+            $arguments[] = '--coverage-html=' . $coveragePath;
+            $arguments[] = '--testdox-html=' . $coveragePath . '/testdox.html';
+            $arguments[] = '--coverage-clover=' . $coveragePath . '/clover.xml';
+        }
+
+        $coverageReportPath = $coveragePath . '/coverage.php';
+        $arguments[] = '--coverage-php=' . $coverageReportPath;
+
+        return $coverageReportPath;
+    }
+
+    /**
+     * @param string $coverageReportPath the generated `coverage-php` report path
+     * @param float $minimumCoverage the required line coverage percentage
+     * @param OutputInterface $output the output interface to log validation results
+     *
+     * @return int the final status code after validating minimum coverage
+     */
+    private function validateMinimumCoverage(
+        string $coverageReportPath,
+        float $minimumCoverage,
+        OutputInterface $output,
+    ): int {
+        try {
+            $coverageSummary = $this->coverageSummaryLoader->load($coverageReportPath);
+        } catch (RuntimeException $exception) {
+            $output->writeln('<error>' . $exception->getMessage() . '</error>');
+
+            return self::FAILURE;
+        }
+
+        $message = \sprintf(
+            'Minimum line coverage of %01.2F%% %s. Current coverage: %s (%d/%d lines).',
+            $minimumCoverage,
+            $coverageSummary->percentage() >= $minimumCoverage ? 'satisfied' : 'was not met',
+            $coverageSummary->percentageAsString(),
+            $coverageSummary->executedLines(),
+            $coverageSummary->executableLines(),
+        );
+
+        if ($coverageSummary->percentage() >= $minimumCoverage) {
+            $output->writeln('<info>' . $message . '</info>');
+
+            return self::SUCCESS;
+        }
+
+        $output->writeln('<error>' . $message . '</error>');
+
+        return self::FAILURE;
+    }
 }

src/PhpUnit/Coverage/CoverageSummary.php

@@ -0,0 +1,70 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of fast-forward/dev-tools.
+ *
+ * This source file is subject to the license bundled
+ * with this source code in the file LICENSE.
+ *
+ * @copyright Copyright (c) 2026 Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
+ * @license   https://opensource.org/licenses/MIT MIT License
+ *
+ * @see       https://github.com/php-fast-forward/dev-tools
+ * @see       https://github.com/php-fast-forward
+ * @see       https://datatracker.ietf.org/doc/html/rfc2119
+ */
+
+namespace FastForward\DevTools\PhpUnit\Coverage;
+
+/**
+ * Represents the line coverage summary extracted from a PHPUnit `coverage-php` report.
+ */
+final readonly class CoverageSummary
+{
+    /**
+     * @param int $executedLines the number of executable lines that were covered
+     * @param int $executableLines the total number of executable lines
+     */
+    public function __construct(
+        private int $executedLines,
+        private int $executableLines,
+    ) {}
+
+    /**
+     * @return int the number of covered executable lines
+     */
+    public function executedLines(): int
+    {
+        return $this->executedLines;
+    }
+
+    /**
+     * @return int the total number of executable lines
+     */
+    public function executableLines(): int
+    {
+        return $this->executableLines;
+    }
+
+    /**
+     * @return float the executed line coverage percentage
+     */
+    public function percentage(): float
+    {
+        if (0 === $this->executableLines) {
+            return 100.0;
+        }
+
+        return ($this->executedLines / $this->executableLines) * 100;
+    }
+
+    /**
+     * @return string the formatted executed line coverage percentage
+     */
+    public function percentageAsString(): string
+    {
+        return \sprintf('%01.2F%%', $this->percentage());
+    }
+}

src/PhpUnit/Coverage/CoverageSummaryLoader.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of fast-forward/dev-tools.
+ *
+ * This source file is subject to the license bundled
+ * with this source code in the file LICENSE.
+ *
+ * @copyright Copyright (c) 2026 Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
+ * @license   https://opensource.org/licenses/MIT MIT License
+ *
+ * @see       https://github.com/php-fast-forward/dev-tools
+ * @see       https://github.com/php-fast-forward
+ * @see       https://datatracker.ietf.org/doc/html/rfc2119
+ */
+
+namespace FastForward\DevTools\PhpUnit\Coverage;
+
+use RuntimeException;
+use SebastianBergmann\CodeCoverage\CodeCoverage;
+
+use function is_file;
+
+/**
+ * Loads line coverage metrics from the serialized PHPUnit `coverage-php` output.
+ */
+final readonly class CoverageSummaryLoader implements CoverageSummaryLoaderInterface
+{
+    /**
+     * @param string $coverageReportPath the path to the PHPUnit `coverage-php` report
+     *
+     * @return CoverageSummary the extracted line coverage summary
+     */
+    public function load(string $coverageReportPath): CoverageSummary
+    {
+        if (! is_file($coverageReportPath)) {
+            throw new RuntimeException(\sprintf('PHPUnit coverage report not found: %s', $coverageReportPath));
+        }
+
+        /** @var mixed $coverage */
+        $coverage = require $coverageReportPath;
+
+        if (! $coverage instanceof CodeCoverage) {
+            throw new RuntimeException(\sprintf('PHPUnit coverage report is invalid: %s', $coverageReportPath));
+        }
+
+        $report = $coverage->getReport();
+
+        return new CoverageSummary($report->numberOfExecutedLines(), $report->numberOfExecutableLines());
+    }
+}