Download the PHP package lucinda/unit-testing without Composer

Lucinda Unit Testing

Lightweight PHP 8.1 unit testing library with no package dependencies. It reads an XML configuration, mirrors source classes into test classes, runs matching test methods, and reports Lucinda\UnitTest\Result objects in the console or as JSON.

Requirements

• PHP 8.1 or newer
• PHP extensions: SimpleXML, cURL, PDO, tokenizer
• Composer PSR-4 autoloading for Lucinda\UnitTest\

Install it in the project that owns the code you want to test:

Configuration

Create an XML file, commonly unit-tests.xml, that describes one or more source/test folder pairs:

unit_tests is required. Each unit_test entry requires sources and tests tags with non-empty namespace attributes. The path attributes default to src and tests; the source path must already exist, while a missing tests path is created automatically.

The optional servers/sql/{environment}/server entry configures the SQL validator. The environment name is the second argument passed to a controller, for example local.

Running Tests

Create a small runner script in the consuming project:

Then run it:

You can run a single generated test class by passing its fully qualified name as the third controller argument:

Runtime Flow

Lucinda\UnitTest\Controller coordinates the whole process:

1. Configuration reads the XML file, validates configured APIs, and builds an optional SQL data source for the selected environment.
2. Creator scans configured source folders and creates or updates missing test classes and methods.
3. Runner scans sources and tests, executes matching test methods, and collects Runner\UnitTest rows.
4. A concrete controller displays or exports the collected results.

The package includes two controllers:

You can also extend Controller and implement handle(array $results): void to store or render results differently.

Generated Tests

The generator scans PHP files under each configured source path. Concrete classes are mirrored into the tests path using the same relative file structure, the source class name with Test appended, and a Test\ namespace prefix.

For example:

Only concrete classes are generated and run. Abstract classes, interfaces, and enums are skipped. Public methods are mirrored, excluding __construct and __destruct. Public inherited and implemented interface methods are included when the parent/interface is found in the configured scan results.

Generated methods are intentionally empty:

Fill each generated method with assertions. A test method must return either one Lucinda\UnitTest\Result or a non-empty array of Result objects:

If a source class or source method is not covered, or if a test method returns something other than Result or Result[], the runner records a failed result.

Additional public methods that exist only on the test class are also executed. This is useful for setup-specific checks that do not directly mirror one source method.

Results

Lucinda\UnitTest\Result is the common assertion payload:

Use hasPassed(): bool to read status and getMessage(): string to read the message. Validators return this object directly.

Validators

Primitive and filesystem validators wrap a value and expose assertion methods that return Result.

Examples:

SQL Assertions

SQL assertions use a shared Validator\SQL instance configured from XML by the runner. The connection is opened through PDO, starts a transaction, and rolls back when the instance is destroyed.

If no SQL data source is configured, SQL::getInstance() throws Lucinda\UnitTest\Exception.

URL Assertions

URL assertions use cURL through Validator\URL. Configure a Validator\URL\DataSource, run the request, and validate the Validator\URL\Response.

Supported request methods are GET, POST, PUT, HEAD, DELETE, PATCH, and OPTIONS. GET parameters are appended as a query string; other request parameters are sent as URL-encoded fields. Requests time out after 10 seconds.

Notes And Constraints

• The runner expects test classes to be autoloadable before it instantiates them.
• Class discovery is file based and scans .php files recursively.
• The source/test namespace attributes are required by configuration, but generated class names are derived from parsed source classes and the hard-coded Test\ prefix.
• Creator writes missing classes and appends missing methods to existing test files. Review generated files before committing them.
• ConsoleController uses the package's internal Message\Table renderer; there is no external console table dependency.