PHPackages                             hampel/xenforo-test-framework - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Testing & Quality](/categories/testing)
4. /
5. hampel/xenforo-test-framework

ActiveLibrary[Testing & Quality](/categories/testing)

hampel/xenforo-test-framework
=============================

Unit testing framework for XenForo

3.0.3(1y ago)24.3k↓50%MITPHPPHP >=8.1.0

Since Nov 19Pushed 1y ago1 watchersCompare

[ Source](https://github.com/hampel/xenforo-test-framework)[ Packagist](https://packagist.org/packages/hampel/xenforo-test-framework)[ Docs](https://xenforo.com/community/resources/unit-testing-xenforo-addons-tutorial.7508/)[ RSS](/packages/hampel-xenforo-test-framework/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (2)Versions (16)Used By (0)

XenForo Addon Unit Test Framework
=================================

[](#xenforo-addon-unit-test-framework)

[![Latest Version on Packagist](https://camo.githubusercontent.com/59cd8146842649cd950b5d4b86490c1a8c1f8f34c5e146b89be879080de23842/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f68616d70656c2f78656e666f726f2d746573742d6672616d65776f726b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/hampel/xenforo-test-framework)[![Total Downloads](https://camo.githubusercontent.com/aab2018728a3337772094de71b24f02d15f60e631ccd6f7cad1f04de6936d27b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f68616d70656c2f78656e666f726f2d746573742d6672616d65776f726b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/hampel/xenforo-test-framework)[![Open Issues](https://camo.githubusercontent.com/d93d07445b3fb546c25ffdc4b17605f963124373ee198d99caa751b16f21d959/68747470733a2f2f696d672e736869656c64732e696f2f6269746275636b65742f6973737565732f68616d70656c2f78656e666f726f2d746573742d6672616d65776f726b2e7376673f7374796c653d666c61742d737175617265)](https://bitbucket.org/hampel/xenforo-test-framework/issues)[![License](https://camo.githubusercontent.com/7639f1bc7421fbb5348a8e3ae2e11c2f65fde829507c481702fbbcaa779b7033/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f68616d70656c2f78656e666f726f2d746573742d6672616d65776f726b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/hampel/xenforo-test-framework)

Unit testing framework for XenForo

Compatibilty
------------

[](#compatibilty)

The test framework is specific to the version of XenForo being run. Given this is a development tool, simply install the appropriate version of the test framework in your addon based on what version of XenForo you are developing on.

XenForoUnit Test Frameworkv2.1v1.xv2.2v2.xv2.3v3.xUpgrading
---------

[](#upgrading)

**Unit Test Framework v2.1**

The `TestCase.php` and `CreatesApplication.php` files have been updated in v2.1 of the unit test framework and you should edit these files in your addon unit test directory to merge in these changes.

Specifically, there is a new variable in `TestCase.php`:

```
protected $addonsToLoad = [];
```

... and some new code in `CreatesApplication.php` which should be copied across to your own version of this file:

```
$options['xf-addons'] = $this->addonsToLoad ?: [];
```

1. Introduction
---------------

[](#1-introduction)

Unit testing is a process by which individual components (units) of your software are tested. The objective is to isolate a section of code and validate its correctness - ensure that it behaves as expected for the given inputs.

There are multiple levels of testing typically used in software development, including Unit testing, Integration testing, System testing, Acceptance testing and so on. Unit testing is generally the lowest level of testing performed and the goal is to test a small section of code in isolation. Each test should run independently and should have no side effects on future tests. Ideally, unit tests should cover all potential code paths through the code being tested and verify that invalid inputs cause the expected failures.

Unit testing is typically executed using tools designed to run a suite of tests, reporting back to the developer on the success or failure of each test. The most popular and widely unit testing framework for PHP is [PHPUnit](https://phpunit.de/). Learning how to use PHPUnit when developing PHP applications will make your code more robust, help you identify issues early on in the development lifecycle and generally make your code cleaner and more maintainable.

The most useful thing I've found with unit testing - other than the obvious debugging process - is when making major changes to your codebase, such as refactoring or upgrading to a new version of a framework or library being used. Having a comprehensive set of unit tests working before you begin, allows you to quickly identify code that no longer works the way it used to or should.

There are lots of tutorials on how to use PHPUnit and unit testing in general - I'm not going to cover that here. The purpose of this tutorial is to explain the theory and process behind unit testing XenForo addons.

Testing within a monolithic application framework such as XenForo can be problematic - especially given that we are not building stand-alone applications, but instead we are extending or adding functionality to an existing application.

One of the most important functions of unit testing is isolating your code from the surrounding framework and swapping out other code with test stubs, mock objects, fakes and test harnesses - which allow you to inject expected behaviours or responses from external code for testing purposes and avoiding side effects.

Fortunately, XenForo v2 has been architected in a way that makes it much easier for us to isolate parts of the framework and inject mock objects.

2. XenForo Application Container
--------------------------------

[](#2-xenforo-application-container)

One of the most significant architectural decisions made by the XenForo developers when designing XenForo v2 was to implement an application container pattern. The application container gives us a central location from which to gain access to all of the subsystems that allow XenForo to run - whether that is to access the database, send an email, create an alert, and so on.

What makes this so significant is that the container pattern also allows us to simply swap out those subsystems with systems of our own that can mimic or mock the behaviour we want to see for our testing purposes.

So for example, rather than actually sending an email - we can swap out the mail handling classes with mock objects that pretend to do the same thing without actually causing emails to be sent. It would be rather annoying to be sending lots of emails every time you ran your test suite!

What's more - we can set expectations on those mock classes to ensure that specific methods were called, perhaps with a certain set of parameters - as part of validating that our code executed as expected for our tests.

To make unit testing of XenForo addons easier, I have developed a unit testing framework which relies on the ability to arbitrarily swap out the subsystems from the application container with mock objects and application stubs - both for setting expectations and for avoiding side effects from our testing.

3. XenForo Application Architecture
-----------------------------------

[](#3-xenforo-application-architecture)

To understand how we execute unit tests against our addons, we first need to understand how XenForo executes.

There are two possible execution triggers that we interact with as users or administrators of XenForo. The first is obviously the web interface. When we visit a XenForo site in our browser, the web server redirects our request via `{forum_root}/index.php`

If you look at this file, it's pretty simple (comments are mine):

```