README

Valkyrja PHPUnit

Shared PHPUnit configuration for Valkyrja PHP projects — custom assertions, a reusable test case base class, and a workflow that runs PHPUnit across consuming repositories.

Overview

This repository provides ValkyrjaTestCase, an abstract base class that extends PHPUnit's TestCase with additional assertion helpers used across the Valkyrja monorepo.

Installation

composer require valkyrja/phpunit

Usage

Extend ValkyrjaTestCase (or the provided PhpUnitTestCase subclass) in your test classes to gain access to the additional assertions:

use Valkyrja\PhpUnit\Abstract\ValkyrjaTestCase;

final class MyTest extends ValkyrjaTestCase
{
    public function testSomething(): void
    {
        self::assertIsA(MyInterface::class, MyClass::class);
    }
}

Additional Assertions

assertIsA(string $expected, string $actual)

Asserts that $actual is $expected or one of its descendants/implementations, using is_a() with $allow_string = true.

self::assertIsA(ParentClass::class, ChildClass::class);
self::assertIsA(MyInterface::class, MyClass::class);

assertMethodExists(object|string $class, string $method)

Asserts that $method exists on the given class name or object instance.

self::assertMethodExists(MyClass::class, 'myMethod');
self::assertMethodExists(new MyClass(), 'myMethod');

assertClassExists(string $class)

Asserts that the given class name resolves to a loadable class.

self::assertClassExists(MyClass::class);

assertInterfaceExists(string $interface)

Asserts that the given name resolves to a loadable interface.

self::assertInterfaceExists(MyInterface::class);

assertTraitExists(string $trait)

Asserts that the given name resolves to a loadable trait.

self::assertTraitExists(MyTrait::class);

assertSameCount(array|Countable $expected, array|Countable $actual)

Asserts that $actual has the same number of elements as $expected.

self::assertSameCount($expectedCollection, $actualCollection);

isA(string $expected, string $actual)

Alias for assertIsA.

self::isA(ParentClass::class, ChildClass::class);

Workflows

The _workflow-call.yml reusable workflow runs PHPUnit against the calling repository's source. It is designed to be called from other repositories via workflow_call.

Inputs

Usage

jobs:
  phpunit:
    uses: valkyrjaio/ci-phpunit-php/.github/workflows/_workflow-call.yml@26.x
    permissions:
      pull-requests: write
      contents: read
    with:
      php-versions: '["8.4", "8.5"]'
      php-version-bleeding-edge: '8.5'
      paths: |
        ci:
          - '.github/ci/phpunit/**'
          - '.github/workflows/phpunit.yml'
        files:
          - '.github/ci/phpunit/**'
          - '.github/workflows/phpunit.yml'
          - 'src/**/*.php'
          - 'tests/**/*.php'
          - 'composer.json'
    secrets: inherit

secrets: inherit is required to pass the VALKYRJA_GHA_APP_ID and VALKYRJA_GHA_PRIVATE_KEY org secrets used for PR comments.

Contributing

See CONTRIBUTING.md for the submission process and VOCABULARY.md for the terminology used across Valkyrja.

Security Issues

If you discover a security vulnerability, please follow our disclosure procedure.

License

Licensed under the MIT license. See LICENSE.md.