Testing Joomla Extensions

<?xml version="1.0" encoding="UTF-8"?>
<phpunit bootstrap="tests/Unit/bootstrap.php" colors="false">
	<testsuites>
		<testsuite name="Unit">
			<directory suffix="Test.php">./tests/Unit</directory>
		</testsuite>
		<testsuite name="Integration">
			<directory suffix="Test.php">./tests/Integration</directory>
		</testsuite>
	</testsuites>
	<php>
		<const name="JTEST_DB_ENGINE" value="mysqli" />
		<const name="JTEST_DB_HOST" value="mysql" />
		<const name="JTEST_DB_NAME" value="test_joomla" />
		<const name="JTEST_DB_USER" value="joomla_ut" />
		<const name="JTEST_DB_PASSWORD" value="joomla_ut" />
	</php>
</phpunit>

<?php

// tests/bootstrap.php

$joomlaRoot = getenv('JOOMLA_ROOT') ?: dirname(__DIR__) . '/.joomla';

if (!is_file($joomlaRoot . '/tests/Unit/bootstrap.php')) {
    fwrite(STDERR, "Set JOOMLA_ROOT to a Joomla 6.2 checkout on which 'composer install' has run.\n");
    exit(1);
}

// The core bootstrap derives every JPATH_* constant from the working directory.
chdir($joomlaRoot);
require $joomlaRoot . '/tests/Unit/bootstrap.php';

// The extension is not installed in that checkout, so teach the autoloader where its classes live.
$prefixes = [
    'Tallpine\\Component\\Tallpine\\Administrator\\' => dirname(__DIR__) . '/com_tallpine/admin/src/',
    'Tallpine\\Component\\Tallpine\\Site\\'          => dirname(__DIR__) . '/com_tallpine/site/src/',
    'Tallpine\\Module\\NextHikes\\Site\\'             => dirname(__DIR__) . '/mod_tallpine_nexthikes/src/',
    'Tallpine\\Plugin\\Content\\TallpineConditions\\' => dirname(__DIR__) . '/plg_content_tallpine_conditions/src/',
    'Tallpine\\Tests\\'                              => __DIR__ . '/',
];

spl_autoload_register(static function (string $class) use ($prefixes): void {
    foreach ($prefixes as $prefix => $directory) {
        if (str_starts_with($class, $prefix)) {
            $file = $directory . str_replace('\\', '/', substr($class, strlen($prefix))) . '.php';

            if (is_file($file)) {
                require $file;
            }

            return;
        }
    }
});

{
  "name": "tallpine/pkg_tallpine",
  "type": "project",
  "require-dev": {
    "phpunit/phpunit": "^12.5",
    "friendsofphp/php-cs-fixer": "^3.94",
    "phpstan/phpstan": "^2.1"
  },
  "config": { "sort-packages": true },
  "scripts": {
    "test": "phpunit --testsuite Unit",
    "test:integration": "phpunit --testsuite Integration"
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<phpunit bootstrap="tests/bootstrap.php" colors="true" failOnDeprecation="false" failOnWarning="true">
  <testsuites>
    <testsuite name="Unit">
      <directory suffix="Test.php">tests/Unit</directory>
    </testsuite>
    <testsuite name="Integration">
      <directory suffix="Test.php">tests/Integration</directory>
    </testsuite>
  </testsuites>
  <php>
    <env name="JTEST_DB_ENGINE" value="mysqli" force="false"/>
    <env name="JTEST_DB_HOST" value="127.0.0.1" force="false"/>
    <env name="JTEST_DB_NAME" value="test_tallpine" force="false"/>
    <env name="JTEST_DB_USER" value="tallpine_ut" force="false"/>
    <env name="JTEST_DB_PASSWORD" value="CHANGE_ME" force="false"/>
  </php>
</phpunit>

<?php

namespace Tallpine\Tests\Unit;

use Joomla\Database\DatabaseInterface;
use Joomla\Database\DatabaseQuery;

trait DatabaseStubTrait
{
    /**
     * Builds a DatabaseInterface stub whose query builder is fluent and whose loaders return fixed values.
     *
     * @param   mixed  $loadResult      Returned by loadResult().
     * @param   array  $loadObjectList  Returned by loadObjectList().
     */
    protected function createDatabaseStub(mixed $loadResult = null, array $loadObjectList = []): DatabaseInterface
    {
        $query = $this->createStub(DatabaseQuery::class);

        foreach (['select', 'from', 'where', 'whereIn', 'bind', 'order', 'setLimit'] as $method) {
            $query->method($method)->willReturnSelf();
        }

        $db = $this->createStub(DatabaseInterface::class);
        $db->method('createQuery')->willReturn($query);
        $db->method('quoteName')->willReturnArgument(0);
        $db->method('setQuery')->willReturnSelf();
        $db->method('loadResult')->willReturn($loadResult);
        $db->method('loadObjectList')->willReturn($loadObjectList);

        return $db;
    }
}

<?php

namespace Tallpine\Tests\Unit\Plugin\Content\TallpineConditions;

use Joomla\CMS\Event\Content\ContentPrepareEvent;
use Joomla\Registry\Registry;
use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\Attributes\TestDox;
use PHPUnit\Framework\TestCase;
use Tallpine\Plugin\Content\TallpineConditions\Extension\TallpineConditions;
use Tallpine\Tests\Unit\DatabaseStubTrait;

#[TestDox('The Tallpine conditions plugin')]
class TallpineConditionsTest extends TestCase
{
    use DatabaseStubTrait;

    private function createPlugin(mixed $closedUntil): TallpineConditions
    {
        $plugin = new TallpineConditions(['params' => []]);
        $plugin->setDatabase($this->createDatabaseStub($closedUntil));

        return $plugin;
    }

    private function createEvent(string $context, \stdClass $item): ContentPrepareEvent
    {
        return new ContentPrepareEvent('onContentPrepare', [
            'context' => $context,
            'subject' => $item,
            'params'  => new Registry(),
            'page'    => 0,
        ]);
    }

    #[TestDox('subscribes to onContentPrepare')]
    public function testSubscribedEvents(): void
    {
        $this->assertSame(['onContentPrepare' => 'onContentPrepare'], TallpineConditions::getSubscribedEvents());
    }

    #[TestDox('appends the closure notice to a trail')]
    public function testAppendsNotice(): void
    {
        $item = (object) ['id' => 42, 'text' => '<p>Ridge loop</p>'];

        $this->createPlugin('2026-11-15')->onContentPrepare($this->createEvent('com_tallpine.trail', $item));

        $this->assertStringContainsString('Closed until 2026-11-15', $item->text);
        $this->assertStringStartsWith('<p>Ridge loop</p>', $item->text);
    }

    #[TestDox('leaves other contexts alone')]
    public function testIgnoresOtherContexts(): void
    {
        $item = (object) ['id' => 7, 'text' => '<p>News</p>'];

        $this->createPlugin('2026-11-15')->onContentPrepare($this->createEvent('com_content.article', $item));

        $this->assertSame('<p>News</p>', $item->text);
    }

    #[TestDox('adds nothing when the trail is open')]
    public function testOpenTrail(): void
    {
        $item = (object) ['id' => 42, 'text' => '<p>Ridge loop</p>'];

        $this->createPlugin(null)->onContentPrepare($this->createEvent('com_tallpine.trail', $item));

        $this->assertSame('<p>Ridge loop</p>', $item->text);
    }

    #[DataProvider('hostileDates')]
    #[TestDox('escapes the stored date: $stored')]
    public function testEscapesOutput(string $stored): void
    {
        $item = (object) ['id' => 42, 'text' => ''];

        $this->createPlugin($stored)->onContentPrepare($this->createEvent('com_tallpine.trail', $item));

        $this->assertStringNotContainsString('<script>', $item->text);
    }

    public static function hostileDates(): iterable
    {
        yield 'script tag' => ['<script>alert(1)</script>'];
        yield 'attribute break' => ['" onmouseover="x'];
    }
}

export JOOMLA_ROOT="$PWD/.joomla"
composer install
./vendor/bin/phpunit --testsuite Unit --testdox

<?php

namespace Tallpine\Tests\Unit\Module\NextHikes;

use Joomla\CMS\Application\SiteApplication;
use Joomla\CMS\User\User;
use Joomla\Registry\Registry;
use PHPUnit\Framework\TestCase;
use Tallpine\Module\NextHikes\Site\Helper\TallpineNexthikesHelper;
use Tallpine\Tests\Unit\DatabaseStubTrait;

class HelperTest extends TestCase
{
    use DatabaseStubTrait;

    public function testReturnsEmptyListWhenNothingIsScheduled(): void
    {
        $user = $this->createStub(User::class);
        $user->method('getAuthorisedViewLevels')->willReturn([1, 5]);

        $app = $this->createStub(SiteApplication::class);
        $app->method('getIdentity')->willReturn($user);
        $app->method('getLanguageFilter')->willReturn(false);

        $helper = new TallpineNexthikesHelper();
        $helper->setDatabase($this->createDatabaseStub(null, []));

        $this->assertSame([], $helper->getHikes(new Registry(['count' => 99]), $app));
    }
}

<?php

namespace Tallpine\Tests\Unit\Component;

use Joomla\CMS\Categories\CategoryFactoryInterface;
use Joomla\CMS\Component\Router\RouterFactoryInterface;
use Joomla\CMS\Dispatcher\ComponentDispatcherFactoryInterface;
use Joomla\CMS\Extension\ComponentInterface;
use Joomla\CMS\HTML\Registry;
use Joomla\CMS\MVC\Factory\MVCFactoryInterface;
use Joomla\DI\Container;
use Joomla\DI\ServiceProviderInterface;
use PHPUnit\Framework\TestCase;
use Tallpine\Component\Tallpine\Administrator\Extension\TallpineComponent;

class ProviderTest extends TestCase
{
    public function testProviderBuildsTheExtensionObject(): void
    {
        /** @var ServiceProviderInterface $provider */
        $provider = require dirname(__DIR__, 3) . '/com_tallpine/admin/services/provider.php';

        $container = new Container();
        $provider->register($container);

        // Replace the services that need a booted application.
        $container->set(ComponentDispatcherFactoryInterface::class, $this->createStub(ComponentDispatcherFactoryInterface::class));
        $container->set(Registry::class, $this->createStub(Registry::class));
        $container->set(MVCFactoryInterface::class, $this->createStub(MVCFactoryInterface::class));
        $container->set(CategoryFactoryInterface::class, $this->createStub(CategoryFactoryInterface::class));
        $container->set(RouterFactoryInterface::class, $this->createStub(RouterFactoryInterface::class));

        $this->assertInstanceOf(TallpineComponent::class, $container->get(ComponentInterface::class));
    }
}

<?php

namespace Tallpine\Tests\Integration;

use Joomla\Database\DatabaseDriver;
use Joomla\Database\DatabaseFactory;
use PHPUnit\Framework\TestCase;

abstract class DatabaseTestCase extends TestCase
{
    private static ?DatabaseDriver $driver = null;

    protected static function db(): DatabaseDriver
    {
        if (self::$driver === null) {
            self::$driver = (new DatabaseFactory())->getDriver(
                getenv('JTEST_DB_ENGINE') ?: 'mysqli',
                [
                    'host'     => getenv('JTEST_DB_HOST') ?: '127.0.0.1',
                    'user'     => getenv('JTEST_DB_USER') ?: 'tallpine_ut',
                    'password' => getenv('JTEST_DB_PASSWORD') ?: '',
                    'database' => getenv('JTEST_DB_NAME') ?: 'test_tallpine',
                    'port'     => getenv('JTEST_DB_PORT') ?: null,
                    'prefix'   => 'tp_',
                ]
            );

            self::installSchema(self::$driver);
        }

        return self::$driver;
    }

    /**
     * Runs the extension's own install script for the engine under test.
     */
    private static function installSchema(DatabaseDriver $db): void
    {
        $engine = str_starts_with(getenv('JTEST_DB_ENGINE') ?: 'mysqli', 'pg') ? 'postgresql' : 'mysql';
        $file   = dirname(__DIR__, 2) . '/com_tallpine/admin/sql/install.' . $engine . '.utf8.sql';

        // Table prefix substitution is done by the driver when a query is set.
        foreach (array_filter(array_map('trim', explode(";\n", (string) file_get_contents($file)))) as $statement) {
            $db->setQuery($statement)->execute();
        }
    }

    protected function setUp(): void
    {
        parent::setUp();
        self::db()->transactionStart();
    }

    protected function tearDown(): void
    {
        self::db()->transactionRollback();
        parent::tearDown();
    }
}

<?php

namespace Tallpine\Tests\Integration;

use Tallpine\Component\Tallpine\Administrator\Service\TrailRepository;

class TrailRepositoryTest extends DatabaseTestCase
{
    public function testFindsPublishedTrailsByDifficulty(): void
    {
        $db = self::db();

        $rows = [
            ['Ridge loop', 'hard', 1],
            ['Meadow walk', 'easy', 1],
            ['Old quarry', 'hard', 0],
        ];

        foreach ($rows as [$title, $difficulty, $state]) {
            $db->setQuery(
                $db->createQuery()
                    ->insert($db->quoteName('#__tallpine_trails'))
                    ->columns($db->quoteName(['title', 'alias', 'difficulty', 'state', 'access', 'created']))
                    ->values(implode(',', [
                        $db->quote($title),
                        $db->quote(strtolower(str_replace(' ', '-', $title))),
                        $db->quote($difficulty),
                        (int) $state,
                        1,
                        $db->quote('2026-10-30 08:00:00'),
                    ]))
            )->execute();
        }

        $repository = new TrailRepository($db);

        $titles = array_column($repository->findPublishedByDifficulty('hard'), 'title');

        $this->assertSame(['Ridge loop'], $titles);
    }
}

{
  "scripts": {
    "cypress:install": "cypress install",
    "cypress:open": "cypress open --config-file cypress.config.mjs",
    "cypress:run": "cypress run --config-file cypress.config.mjs"
  }
}

git clone --depth 1 https://github.com/joomla/joomla-cms /var/www/html
cd /var/www/html
composer install
npm ci
cp cypress.config.dist.mjs cypress.config.mjs
# edit cypress.config.mjs: set baseUrl and the values under expose
npm run cypress:run

import { defineConfig } from 'cypress';
import setupPlugins from './tests/System/plugins/index.mjs';

export default defineConfig({
  fixturesFolder: 'tests/System/fixtures',
  videosFolder: 'tests/System/output/videos',
  screenshotsFolder: 'tests/System/output/screenshots',
  viewportHeight: 1000,
  viewportWidth: 1200,
  e2e: {
    setupNodeEvents(on, config) {
      setupPlugins(on, config);
    },
    baseUrl: 'https://localhost/',
    specPattern: [
      'tests/System/integration/install/**/*.cy.{js,jsx,ts,tsx}',
      'tests/System/integration/administrator/**/*.cy.{js,jsx,ts,tsx}',
      'tests/System/integration/site/**/*.cy.{js,jsx,ts,tsx}',
      'tests/System/integration/api/**/*.cy.{js,jsx,ts,tsx}',
      'tests/System/integration/plugins/**/*.cy.{js,jsx,ts,tsx}',
      'tests/System/integration/cli/**/*.cy.{js,jsx,ts,tsx}',
    ],
    supportFile: 'tests/System/support/index.js',
    scrollBehavior: 'center',
    browser: 'firefox',
    screenshotOnRunFailure: true,
    video: false,
    allowCypressEnv: false,
  },
  expose: {
    sitename: 'Joomla CMS Test',
    name: 'jane doe',
    email: 'admin@example.com',
    username: 'ci-admin',
    password: 'CHANGE_ME_TEST_ONLY',
    db_type: 'MySQLi',
    db_host: 'localhost',
    db_port: '',
    db_name: 'test_joomla',
    db_user: 'root',
    db_password: '',
    db_prefix: 'jos_',
    smtp_host: 'localhost',
    smtp_port: '1025',
    cmsPath: '.',
    logFile: '',
  },
});

{
  "name": "pkg-tallpine-tests",
  "private": true,
  "engines": { "node": ">=20.0.0" },
  "scripts": {
    "cypress:run": "cypress run --config-file cypress.config.mjs",
    "cypress:open": "cypress open --config-file cypress.config.mjs"
  },
  "devDependencies": {
    "cypress": "^15.18.0",
    "joomla-cypress": "^2.0.0"
  }
}

// cypress.config.mjs
import { defineConfig } from 'cypress';

export default defineConfig({
  e2e: {
    baseUrl: 'http://localhost:8080',
    specPattern: 'tests/System/integration/**/*.cy.js',
    supportFile: 'tests/System/support/index.js',
    screenshotsFolder: 'tests/System/output/screenshots',
    video: false,
    screenshotOnRunFailure: true,
    allowCypressEnv: false,
  },
  // Values for joomla-cypress; the password comes from the shell, never from the repository.
  expose: {
    username: 'ci-admin',
    password: process.env.TALLPINE_ADMIN_PASSWORD ?? 'CHANGE_ME',
    email: 'admin@example.com',
    name: 'Tallpine Admin',
    sitename: 'Tallpine Test',
  },
});

// tests/System/support/index.js
import { registerCommands } from 'joomla-cypress';

registerCommands();

// Fail a test when Joomla prints a PHP notice or warning into the page.
afterEach(() => cy.checkForPhpNoticesOrWarnings());

// Creates or reads the API token of the test administrator (same flow as the core support command api_getBearerToken).
Cypress.Commands.add('tallpine_apiToken', () => {
  cy.session('tallpineApiToken', () => {
    cy.doAdministratorLogin();
    cy.visit('/administrator/index.php?option=com_users&view=users');
    cy.get('a[href*="task=user.edit"]').first().invoke('attr', 'href').then((href) => {
      const id = new URL(href, 'http://localhost').searchParams.get('id');
      cy.visit(`/administrator/index.php?option=com_users&task=user.edit&id=${id}#attrib-joomlatoken`);
    });
    cy.get('#fieldset-joomlatoken').then((fieldset) => {
      if (fieldset.find('#jform_joomlatoken_reset1').length > 0) {
        cy.get('#jform_joomlatoken_reset1').click();
      }
    });
    cy.clickToolbarButton('Save');
    cy.get('#jform_joomlatoken_token').invoke('val').then((token) => {
      window.localStorage.setItem('tallpineToken', token);
    });
  }).then(() => window.localStorage.getItem('tallpineToken'));
});

// tests/System/integration/install/Install.cy.js
describe('Installing pkg_tallpine', () => {
  it('installs the package and its children', () => {
    cy.doAdministratorLogin();
    cy.installExtensionFromFolder('/tmp/build/pkg_tallpine', 'package');
    cy.checkForSystemMessage('Installation of the package was successful');

    cy.visit('/administrator/index.php?option=com_installer&view=manage&filter[search]=tallpine');
    ['pkg_tallpine', 'com_tallpine', 'mod_tallpine_nexthikes', 'Content - Tallpine Conditions'].forEach((name) => {
      cy.contains(name);
    });
  });
});

// tests/System/integration/administrator/Trails.cy.js
describe('Tallpine trails in the administrator', () => {
  beforeEach(() => {
    cy.doAdministratorLogin();
  });

  it('creates a trail and lists it', () => {
    cy.visit('/administrator/index.php?option=com_tallpine&task=trail.add');
    cy.get('#jform_title').clear().type('Ridge loop');
    cy.get('#jform_distance_km').clear().type('12.5');
    cy.clickToolbarButton('Save & Close');

    cy.checkForSystemMessage('Trail saved.');
    cy.contains('Ridge loop');
  });

  it('refuses a trail without a title', () => {
    cy.visit('/administrator/index.php?option=com_tallpine&task=trail.add');
    cy.clickToolbarButton('Save');

    cy.get('#jform_title').should('have.class', 'invalid');
  });
});

// tests/System/integration/api/Trails.cy.js
describe('The Tallpine trails endpoint', () => {
  it('returns published trails as JSON:API', () => {
    cy.tallpine_apiToken().then((token) => {
      cy.request({
        method: 'GET',
        url: '/api/index.php/v1/tallpine/trails',
        headers: { Authorization: `Bearer ${token}`, Accept: 'application/vnd.api+json' },
      }).then((response) => {
        expect(response.status).to.eq(200);
        expect(response.body.data).to.be.an('array');
        response.body.data.forEach((trail) => {
          expect(trail.type).to.eq('trails');
          expect(trail.attributes).to.have.property('title');
        });
      });
    });
  });

  it('rejects a request without a token', () => {
    cy.request({ url: '/api/index.php/v1/tallpine/trails', failOnStatusCode: false })
      .its('status').should('eq', 401);
  });
});

name: Tests
on: [push, pull_request]

jobs:
  unit:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        php: ['8.3', '8.4', '8.5']
    steps:
      - uses: actions/checkout@v6
      - uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php }}
          extensions: mbstring, gd, intl, pdo_mysql, mysqli, pgsql, pdo_pgsql
      - name: Fetch a Joomla 6.2 checkout
        run: |
          git clone --depth 1 --branch 6.2-dev https://github.com/joomla/joomla-cms .joomla
          composer install --working-dir=.joomla --no-progress
      - run: composer install --no-progress
      - run: JOOMLA_ROOT="$PWD/.joomla" ./vendor/bin/phpunit --testsuite Unit

  integration:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        include:
          - { engine: mysqli, php: '8.3', image: 'mariadb:10.4', port: 3306 }
          - { engine: mysqli, php: '8.5', image: 'mariadb:12.0', port: 3306 }
          - { engine: pgsql, php: '8.3', image: 'postgres:12', port: 5432 }
          - { engine: pgsql, php: '8.5', image: 'postgres:18', port: 5432 }
    services:
      db:
        image: ${{ matrix.image }}
        env:
          MARIADB_ROOT_PASSWORD: ${{ secrets.TEST_DB_PASSWORD }}
          MARIADB_DATABASE: test_tallpine
          POSTGRES_PASSWORD: ${{ secrets.TEST_DB_PASSWORD }}
          POSTGRES_DB: test_tallpine
        ports: ['${{ matrix.port }}:${{ matrix.port }}']
    steps:
      - uses: actions/checkout@v6
      - uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php }}
          extensions: mbstring, gd, intl, mysqli, pgsql
      - run: |
          git clone --depth 1 --branch 6.2-dev https://github.com/joomla/joomla-cms .joomla
          composer install --working-dir=.joomla --no-progress
          composer install --no-progress
      - name: Integration tests
        env:
          JOOMLA_ROOT: ${{ github.workspace }}/.joomla
          JTEST_DB_ENGINE: ${{ matrix.engine }}
          JTEST_DB_HOST: 127.0.0.1
          JTEST_DB_PORT: ${{ matrix.port }}
          JTEST_DB_USER: ${{ matrix.engine == 'pgsql' && 'postgres' || 'root' }}
          JTEST_DB_PASSWORD: ${{ secrets.TEST_DB_PASSWORD }}
        run: ./vendor/bin/phpunit --testsuite Integration

git clone https://github.com/joomla/joomla-cms.git
mv joomla-cms jcms-62
cd jcms-62
git checkout 6.2-dev
composer install
npm ci
# then open http://localhost/jcms-62 and run the web installer