Search by

adachsoft / scheduler-contract-tests

Arkadiusz Adach

Reusable PHPUnit contract tests and test support for scheduler contract implementations.

Package info

gitlab.com/a.adach/scheduler-contract-tests

Issues

pkg:composer/adachsoft/scheduler-contract-tests

Statistics

Installs: 4

Dependents: 1

Suggesters: 0

Stars: 0

v0.1.0 2026-11-19 15:40 UTC

This package is auto-updated.

Last update: 2026-11-19 14:42:53 UTC


README

adachsoft/scheduler-contract-tests provides reusable PHPUnit contract suites and deterministic support classes for implementations of adachsoft/scheduler-contracts. It defines expected behavior for state repositories, locks, run-history repositories, and job executors without providing production scheduler adapters.

Requirements

  • PHP 8.3 or later
  • PHPUnit 12.5 or later
  • An implementation of adachsoft/scheduler-contracts

Installation

Install this package as a development dependency in the project that implements the scheduler contracts:

composer require --dev adachsoft/scheduler-contract-tests

Usage

Repository contracts

Extend the matching abstract contract test and return a new repository object each time its factory is called. Every object created within one test must use the same backing storage. Create isolated storage in setUp() and clear it in tearDown() so tests cannot affect one another.

use AdachSoft\SchedulerContractTests\Contract\AbstractJobStateRepositoryContractTest;
use AdachSoft\SchedulerContracts\State\JobStateRepositoryInterface;

final class SqlStateRepositoryContractTest extends AbstractJobStateRepositoryContractTest
{
    private SqlTestStorage $storage;

    protected function setUp(): void
    {
        parent::setUp();
        $this->storage = new SqlTestStorage();
    }

    protected function tearDown(): void
    {
        $this->storage->clear();
        parent::tearDown();
    }

    protected function createRepository(): JobStateRepositoryInterface
    {
        return new SqlJobStateRepository($this->storage);
    }
}

The state-repository contract covers missing and initial state, complete round trips (including microsecond timestamps and the current run), overwrites, and independence between job identifiers. The lock contract verifies exclusive leases, release, expiry, and isolation by job. The history contract verifies filters, inclusive time bounds, ordering, pagination, complete records, pruning, and persistence across instances.

Using the executor contract

The executor factory must return an executor that recognizes all identifiers in ContractJobIds and executes the corresponding jobs from ContractJobs::all().

use AdachSoft\SchedulerContractTests\Contract\AbstractJobExecutorContractTest;
use AdachSoft\SchedulerContracts\Execution\JobExecutorInterface;

final class ProcessJobExecutorContractTest extends AbstractJobExecutorContractTest
{
    protected function createExecutor(): JobExecutorInterface
    {
        return new ProcessJobExecutor(ContractJobs::all());
    }
}

The executor contract checks successful results, failure conversion, and hard timeout behavior. An executor that runs jobs in-process and cannot enforce a hard timeout may override supportsHardTimeout() to return false; only the hard-timeout test will then be skipped.

Factory and storage semantics

Each contract test may call its factory more than once. Every call must return a new adapter instance, while all instances created during that test must share the same storage, so the suite can model separate processes reading persisted data. Storage must be isolated between tests, typically by creating a fresh backend in setUp() and clearing or discarding it in tearDown().

FrozenClock implements PSR-20 ClockInterface with UTC-normalized time and controllable advancement. ContractJobs provides a successful job, a failing job, and a sleeping job for executor implementations.

More usage examples are available in docs/examples/.