How to group / reuse / mix custom assertions classes for phpunit testcases?

PHPUnit defines its Assertions as public static methods.

Hence, your own custom Assertions can call its assertions via static access:

TestCase::assertTrue(...)

That means one can use traits as you don't need to extend the TestCase anymore. You just define them as such:

<?php

namespace Kopernikus\TimrReportManager;

use PHPUnit\Framework\TestCase;

trait ArrayContainsValueTrait
{
    public static function assertArrayOnlyContainsTrue(array $haystack): void
    {
        static::assertArrayOnlyContainsSameValue(true, $haystack);
    }

    public static function assertArrayOnlyContainsSameValue(mixed $expectedValue, array $haystack): void
    {
        $haystack = array_unique($haystack);
        TestCase::assertTrue(static::areOnlySameValuesInArray($expectedValue, $haystack), message: 'The array contains of different values, yet sameness was expected');
    }

    private static function areOnlySameValuesInArray(mixed $expectedValue, array $haystack): bool
    {
        $haystack = array_unique($haystack);

        if (count($haystack) !== 1) {
            return false;
        }

        return reset($haystack) === $expectedValue;
    }

    public static function assertArrayOnlyContainsFalse(array $haystack)
    {
        static::assertArrayOnlyContainsSameValue(false, $haystack);

    }
}

<?php

namespace Kopernikus\TimrReportManager;

use Kopernikus\TimrReportManager\Dto\TimeEntry;
use PHPUnit\Framework\TestCase;

trait TimeEntryAssertionsTrait
{
    public static function assertTimeEntryHasTicketId(TimeEntry $timeEntry, int $ticketNumber)
    {
        $ticketNumberHashtag = '#' . (string)$ticketNumber;
        $count = substr_count($timeEntry->description, '#');
        TestCase::assertSame(1, $count, 'the time entry must only contain one hashtag for the ticket id');
        TestCase::assertSame($timeEntry->ticket, $ticketNumberHashtag);
    }
}

In your actual TestCase you can then add those traits as needed:

class CsvParserTest extends TestCase
{
    use TimeEntryAssertionsTrait;
    use ArrayContainsValueTrait;

    ...
}

You could even have your custom assertions trait include other traits themselves, just be aware that calling Trait::somePublicMethod() is deprecated and may stop working in the future.

You have to use them within the trait (making it so that the testcase gets access to the other included assertions of that used trait).

Here is a contrived TraitUsingOtherTraits:

<?php

namespace Kopernikus\TimrReportManager\Services;

use Kopernikus\TimrReportManager\ArrayContainsValueTrait;
use Kopernikus\TimrReportManager\Dto\TimeEntry;
use Kopernikus\TimrReportManager\TimeEntryAssertionsTrait;

trait TraitUsingOtherTraits
{
    use ArrayContainsValueTrait;
    use TimeEntryAssertionsTrait;

    /**
     * Contrived dummy assertion, this is no real test
     */
    public static function assertUsingOtherTraits(): void
    {
        static::assertTimeEntryHasTicketId(new TimeEntry('foobar #123', '2024-12-31 13:00', '2024-12-31 15:00'), 123);
        static::assertArrayOnlyContainsTrue([true, true, true]);
    }
}

And it my actual contrived test class I have the method:

    public function testShowcaseTraits()
    {
        static::assertUsingOtherTraits();
    }

which runs just fine:

This is a problem that surely had some consequences in the original design of PhpUnit as well. It is similarly constrained by the single-inheritance rules of PHP and in its earlier versions there were even no traits in PHP that are commonly in use to handle the diamond problem you describe nowadays.

Given the presumption about the extensibility of traits do not finally resolve as an early confusion and you still do not want to use traits here, you can take a look how assertions are implemented in PHP Unit itself.

There is at least a single class per assertion, which is, how I read your question, you strive for.