Talon¶

Overview¶

Talon is the Phalcon test harness. It is the part of Phalcon that catches the bugs. Talon bootstraps a Phalcon test environment and fronts PHPUnit, so any Phalcon project can write unit, database, functional, and browser tests with minimal boilerplate.

Talon provides three things:

• Traits - the framework-neutral core. Each trait carries a group of helpers (reflection, filesystem, database, functional, browser, services).
• PHPUnit base classes - ready-to-extend test cases that compose the traits for each kind of test.
• A command-line runner - vendor/bin/talon, which runs PHPUnit once per mapped suite.

Talon runs on both Phalcon distributions and uses whichever is present:

• Phalcon v5 - the ext-phalcon C extension.
• Phalcon v6 - the phalcon/phalcon PHP package.

The same test suite runs against either one. Talon is used across the Phalcon projects, including cphalcon, the sample applications, and the PHP framework itself. To see it driving the cphalcon suites, see the Testing environment guide.

Requirements¶

• PHP 8.1 or later.
• Phalcon, either the v5 C extension or the v6 phalcon/phalcon package. See the installation page for the extension.
• symfony/browser-kit and symfony/dom-crawler are pulled in as dependencies and power the browser tests.

Installation¶

Install Talon as a development dependency:

composer require --dev phalcon/talon

Bootstrapping Your Tests¶

Point PHPUnit at a bootstrap file that boots Talon. The one-liner form reads configuration from the environment:

<?php

// tests/bootstrap.php

require __DIR__ . '/../vendor/autoload.php';

use Phalcon\Talon\Settings;
use Phalcon\Talon\Talon;

Talon::boot(Settings::fromEnv());

When you need setup hooks (for example, raising the memory limit or creating output directories), use the bootstrap Runner. It runs your callbacks before or after each bootstrap Stage - Stage::Settings, Stage::Environment, and Stage::Directories:

<?php

use Phalcon\Talon\Bootstrap\Runner;
use Phalcon\Talon\Bootstrap\Stage;
use Phalcon\Talon\Settings;

Runner::for(Settings::fromArray(['root' => __DIR__ . '/..']))
    ->before(Stage::Environment, fn () => ini_set('memory_limit', '512M'))
    ->after(Stage::Directories, fn ($settings) => mkdir($settings->outputPath('screens'), 0777, true))
    ->boot();

The Command-Line Runner¶

vendor/bin/talon runs PHPUnit once per mapped suite:

vendor/bin/talon run            # default suite (unit)
vendor/bin/talon run mysql
vendor/bin/talon run mysql pgsql
vendor/bin/talon run all        # every mapped suite, sequentially
vendor/bin/talon suites         # list mapped suites
vendor/bin/talon schema         # generate the schema artifacts

Each suite runs as its own subprocess, so per-suite extensions and environment variables take effect. A single suite forwards its exit code verbatim. Multiple suites print a per-suite summary and exit with the highest code.

Suite discovery¶

With zero configuration, suites are discovered from phpunit*.xml files in the project root and in resources/. phpunit.xml.dist becomes the unit suite (the default), and phpunit.mysql.xml becomes the mysql suite.

Projects that need PHP ini flags or environment variables declare a talon.php at the project root:

<?php

return [
    'php'     => ['extension=ext/modules/phalcon.so'],   // global ini flags, optional
    'suites'  => [
        'unit'    => ['config' => 'resources/phpunit.xml.dist'],
        'mariadb' => ['config' => 'resources/phpunit.mariadb.xml'],
        'mysql'   => ['config' => 'resources/phpunit.mysql.xml'],
        'pgsql'   => ['config' => 'resources/phpunit.pgsql.xml'],
        'sqlite'  => ['config' => 'resources/phpunit.sqlite.xml'],
    ],
    'default' => 'unit',
];

Per-suite keys:

Forwarding arguments to PHPUnit¶

Options are forwarded to PHPUnit starting at the first option Talon does not recognize itself. Everything after -- is always forwarded verbatim:

vendor/bin/talon run unit -- --filter FooTest --testdox

Test Case Base Classes¶

Each base class composes the relevant traits for one kind of test. They live in the Phalcon\Talon\PHPUnit namespace:

Unit tests¶

<?php

use Phalcon\Talon\PHPUnit\AbstractUnitTestCase;

final class CalculatorTest extends AbstractUnitTestCase
{
    public function testInternal(): void
    {
        $this->assertSame(5, $this->callProtectedMethod(new Calculator(), 'add', 2, 3));
    }
}

AbstractUnitTestCase provides callProtectedMethod(), getProtectedProperty(), setProtectedProperty(), invokeMethod(), getNewFileName(), safeDeleteFile(), safeDeleteDirectory(), assertFileContentsContains(), checkExtensionIsLoaded(), and checkPhalconAvailable().

Database tests¶

<?php

use Phalcon\Talon\PHPUnit\AbstractDatabaseTestCase;

final class UserTest extends AbstractDatabaseTestCase
{
    public function testSeeded(): void
    {
        $this->assertInDatabase('users', ['email' => '[email protected]']);
    }
}

The driver comes from the driver environment variable (sqlite, mysql, mariadb, or pgsql). Credentials come from Settings, read from environment variables by default.

Each driver reads its own block, so MySQL and MariaDB are configured independently and can point at different servers:

Two further variables apply to every driver:

MariaDB connects through pdo_mysql, so Settings::getDatabaseDsn('mariadb') returns a DSN carrying the mysql: prefix. No additional PHP extension is required.

DATA_POSTGRES_SCHEMA is applied to the connection as SET search_path immediately after connecting, before any initial_queries run.

Functional tests¶

Talon never owns your container. Hand it your configured application through an appFactory():

<?php

use Phalcon\Talon\PHPUnit\AbstractFunctionalTestCase;

final class HomeTest extends AbstractFunctionalTestCase
{
    protected function appFactory(): callable
    {
        // returns a configured Application or Micro
        return fn () => require __DIR__ . '/../app/bootstrap.php';
    }

    public function testHome(): void
    {
        $this->dispatch('/');
        $this->assertController('index');
        $this->assertResponseContentContains('Welcome');
    }
}

Browser tests¶

For multi-request flows - login, forms, redirects - AbstractBrowserTestCase drives your application in-process, with no web server, through a symfony/browser-kit bridge. Cookies and the session are kept across requests, and redirects are followed automatically:

<?php

use Phalcon\Talon\PHPUnit\AbstractBrowserTestCase;

final class LoginTest extends AbstractBrowserTestCase
{
    protected function appFactory(): callable
    {
        return fn () => require __DIR__ . '/../app/bootstrap.php';
    }

    public function testLogin(): void
    {
        $this->visitPage('/session/login');
        $this->fillField('email', '[email protected]');
        $this->fillField('password', 'password1');
        $this->pressButton('Log In');

        $this->assertPageContainsText('Search users');
    }
}

The browser verbs are visitPage, fillField, selectOption, clickLink, pressButton, and getCookie/setCookie. The assertions are assertPageContainsText and assertPageMissingText. Browser tests require symfony/browser-kit and symfony/dom-crawler, which Talon installs.

Service tests¶

<?php

use Phalcon\Talon\PHPUnit\AbstractServicesTestCase;

final class CacheTest extends AbstractServicesTestCase
{
    public function testRedis(): void
    {
        $this->setRedisKey('key', 'value');
        $this->assertSame('value', $this->getRedisKey('key'));
    }
}

Service tests skip automatically when the backend (Redis or Memcached) is unreachable, so the suite stays green on a host without those services.

The backends read these environment variables:

ServicesTrait provides helpers for Redis and Memcached only. The redisCluster and beanstalk options are read and exposed through Settings::getServiceOptions() for a project to consume, but Talon ships no assertions for them.

Mocking a resultset¶

To assert against model logic without a database, mock a resultset with ResultSetTrait:

<?php

use Phalcon\Talon\Traits\ResultSetTrait;
use PHPUnit\Framework\TestCase;

final class ReportTest extends TestCase
{
    use ResultSetTrait;

    public function testReport(): void
    {
        $resultset = $this->mockResultSet([$modelA, $modelB]);

        $this->assertCount(2, $resultset);
    }
}

Schema Fixtures¶

A schema fixture is a class that declares the DDL for one table, per dialect. Talon generates the SQL artifacts from those classes, and your tests use the same classes to create, truncate, and populate the table.

• MySQL and MariaDB share one set of statements. MariaDB uses the MySQL dialect, so there is no separate method for it.
• PostgreSQL has its own set.
• SQLite has its own set.

Extend Phalcon\Talon\Database\Schema\AbstractSchema and declare the table name and the statements for each dialect. The three per-dialect methods are abstract, so a new dialect cannot be forgotten:

<?php

use Phalcon\Talon\Database\Schema\AbstractSchema;

final class InvoicesSchema extends AbstractSchema
{
    protected string $table = 'co_invoices';

    public function insert(int $id, string $title, float $total): int
    {
        return $this->execute(
            'INSERT INTO co_invoices (inv_id, inv_title, inv_total) '
            . 'VALUES (:id, :title, :total)',
            [':id' => $id, ':title' => $title, ':total' => $total]
        );
    }

    protected function getStatementsMysql(): array
    {
        return [
            'CREATE TABLE `co_invoices` ('
            . '`inv_id` INT(10) UNSIGNED NOT NULL AUTO_INCREMENT, '
            . '`inv_title` VARCHAR(100) NULL, '
            . '`inv_total` DECIMAL(10,2) NOT NULL, '
            . 'PRIMARY KEY (`inv_id`)'
            . ') ENGINE=InnoDB;',
        ];
    }

    protected function getStatementsPgsql(): array
    {
        return [
            'CREATE TABLE co_invoices ('
            . 'inv_id SERIAL PRIMARY KEY, '
            . 'inv_title VARCHAR(100) NULL, '
            . 'inv_total NUMERIC(10,2) NOT NULL'
            . ');',
        ];
    }

    protected function getStatementsSqlite(): array
    {
        return [
            'CREATE TABLE co_invoices ('
            . 'inv_id INTEGER PRIMARY KEY AUTOINCREMENT, '
            . 'inv_title TEXT NULL, '
            . 'inv_total REAL NOT NULL'
            . ');',
        ];
    }
}

Four rules govern the statement lists:

clear() empties the table, but do not assert on its return value. MySQL and PostgreSQL clear with TRUNCATE, which reports no affected rows, so both return 0. Only SQLite's DELETE returns a count.

A fixture whose statements create a second table receives no generated DROP for that table. Write the drop yourself, or split the fixture in two.

Override getDependencies() to declare the tables that must exist first:

<?php

use Phalcon\Talon\Database\Schema\AbstractSchema;

final class InvoiceLinesSchema extends AbstractSchema
{
    protected string $table = 'co_invoice_lines';

    /**
     * @return list<string>
     */
    public function getDependencies(): array
    {
        return ['co_invoices'];
    }

    // getStatementsMysql(), getStatementsPgsql(), getStatementsSqlite() omitted
}

Generating the artifacts¶

vendor/bin/talon schema         # every dialect
vendor/bin/talon schema mysql   # one dialect

The command is driven by five settings, read from the environment or from Settings::fromArray():

schema_pre and schema_post are ordinary AbstractSchema subclasses with an empty $table. Use them for statements that belong to the load as a whole, such as SET FOREIGN_KEY_CHECKS=0 on MySQL or CREATE SCHEMA IF NOT EXISTS on PostgreSQL.

Each dialect is written to its own directory:

schema/mysql/_preSchema.sql     session setup
schema/mysql/co_invoices.sql    the table's DROP, then its creation statements
schema/mysql/manifest.json      load order, dependencies, per-dialect presence
schema/mysql/_postSchema.sql    closes what _preSchema opened

File names follow your table names, so a schema-qualified name keeps its dot: private.co_orders.sql. The manifest is generated, never hand-edited. When it is wrong, correct a fixture class and regenerate.

Loading a schema¶

Point dump_file at the dialect directory. AbstractDatabaseTestCase loads it on the first connection, in this order: _preSchema.sql, the manifest's tables, _postSchema.sql.

<env name="dump_file" value="resources/schema/mysql"/>

Connection::loadSchema() also accepts a single flat .sql file, so a project can move to the directory format on its own schedule.

Rebuilding one table¶

Loading the whole schema once and truncating between tests remains the default. addTable() is the escape hatch for a test that needs one table rebuilt:

<?php

use Phalcon\Talon\PHPUnit\AbstractDatabaseTestCase;

final class InvoiceRebuildTest extends AbstractDatabaseTestCase
{
    public function testRebuild(): void
    {
        $this->addTable('co_invoices');

        $this->assertTrue($this->getConnection()->tableExists('co_invoices'));
    }
}

addTable() is standalone only, and that is enforced. A declared dependency that does not yet exist throws SchemaDependencyMissing. Dependencies are never resolved for you, so call the method once per table, dependency first:

$this->addTable('co_invoices');       // the dependency
$this->addTable('co_invoice_lines');  // the dependent

The restriction is deliberate. schema_pre is in effect only during the bulk load. By the time a test runs, schema_post has restored FOREIGN_KEY_CHECKS=1, so a table with foreign keys that loads correctly in bulk can fail on its own, on MySQL, for reasons the calling test does not suggest.

Traits¶

The traits are the core public API. Compose them directly when you do not want the base classes. They live in the Phalcon\Talon\Traits namespace:

Configuration¶

Configuration is held in a Settings object. The one-liner bootstrap uses Settings::fromEnv(), which reads environment variables. To configure Talon in code, pass Settings::fromArray() to Talon::boot(), or override getSettings() in a project base class:

<?php

use Phalcon\Talon\Settings;
use Phalcon\Talon\Talon;

Talon::boot(
    Settings::fromArray(
        [
            'root' => dirname(__DIR__),
            'db'   => [
                'mysql'  => [
                    'host'     => '127.0.0.1', 
                    'port'     => 3306, 
                    'dbname'   => 'app', 
                    'username' => 'root', 
                    'password' => '',
                ],
                'sqlite' => [
                    'dbname' => ':memory:',
                ],
            ],
        ]
    )
);

Beyond PHPUnit¶

The traits carry no PHPUnit base-class requirement for their non-assertion helpers, so Pest (through uses(...)) and other runners can consume them too. Pest and Codeception adapters are planned for a future release.

References¶

• Talon - GitHub Repository
• Talon on Packagist
• PHPUnit
• Pest
• Symfony BrowserKit
• Testing environment