Title: Tests Author: Javier Casares Published: 2021-02-11 Last modified: 2026-02-11 --- # Tests ## In this article * [What is it](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#what-is-it) - [Runner](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#runner) - [Reporter](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#reporter) * [Try the PHPUnit Test Runner](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#try-the-phpunit-test-runner) - [What’s the phpunit-test-runner](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#whats-the-phpunit-test-runner) - [Requirements](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#requirements) - [Installing the Runner](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#installing-the-runner) - [Preparing the environment](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#preparing-the-environment) - [Preparing the test](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#preparing-the-test) - [Running the test](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#running-the-test) - [Creating a report](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#creating-a-report) - [Cleaning up the environment for other tests](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#cleaning-up-the-environment-for-other-tests) - [Automating the execution](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#automating-the-execution) - [Improving the configuration](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#improving-the-configuration) * [How to report: Creating your bot for WordPress.org](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#how-to-report-creating-your-bot-for-wordpress-org) [↑ Back to top](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#wp--skip-link--target) To improve compatibility with WordPress, the WordPress HostingHosting A web hosting service is a type of Internet hosting service that allows individuals and organizations to make their website accessible via the World Wide Web. Team provides tools for hosting companies to run the WordPress automated tests on their infrastructure to improve compatibility with WordPress. These results can be published on the [Host Test Result information page](https://make.wordpress.org/hosting/test-results/), to communicate their compatibility status with the WordPress community. It consists of two tools: the Runner is the part that runs coreCore Core is the set of software required to run WordPress. The Core Team builds WordPress.’s PHPUnit tests on a host and optionally [sends the information to the results page](https://make.wordpress.org/hosting/test-results/); and the Reporter, which is the pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory or can be cost-based plugin from a third-party. that [works on the hosting page](https://make.wordpress.org/hosting/) and shows the results. ## 󠀁[What is it](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#what-is-it)󠁿 ### 󠀁[Runner](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#runner)󠁿 Hosting companies can have millions of websites hosted with WordPress, so it’s important to make sure their configuration is as compatible as possible with the software. To verify this compatibility, the WordPress Community provides a series of [PHPUnit](https://phpunit.de/) tests with which to check the operation of WordPress in any environment. ### 󠀁[Reporter](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#reporter)󠁿 The Runner tests generate a report with the test results related to a bot user associated with a web host, and this captures and displays those test results at the [Host Test Result](https://make.wordpress.org/hosting/test-results/) page. ## 󠀁[Try the PHPUnit Test Runner](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#try-the-phpunit-test-runner)󠁿 ### 󠀁[What’s the phpunit-test-runner](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#whats-the-phpunit-test-runner)󠁿 The [phpunit-test-runner](https://github.com/WordPress/phpunit-test-runner) is a tool designed to make it easier for hosting companies to run the WordPress project’s automated tests. There is [full documentation about this tool](https://make.wordpress.org/hosting/test-results-getting-started/). Also, if you want, you can make your test results appear in the [Host Test Results page](https://make.wordpress.org/hosting/test-results/) of WordPress. The tool can be run manually or through an automated system like Travis. The purpose of this document is to show how to run the tests manually to illustrate how it works. ### 󠀁[Requirements](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#requirements)󠁿 To use the Runner, the following is required: * A serverServer A server is a piece of computer hardware or software that provides functionality for other programs or devices. Typical servers are database servers, file servers, mail servers, print servers, web servers, game servers, and application servers. / hosting (infrastructure) with the usual configuration you have. * A databaseDatabase A database is an organized collection of data. Access to this data is usually provided by a “database management system” (DBMS) consisting of an integrated set of computer software that allows users to interact with one or more databases and provides access to all of the data contained in the database. Because of the close relationship between them, the term “database” is often used casually to refer to both a database and the DBMS used to manipulate it. where you can test (it will be created and destroyed several times) * NodeJS 20.x #### 󠀁[NodeJS installation](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#nodejs-installation)󠁿 If you are using Debian / Ubuntu, install or update NodeJS with this command: ``` curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt -y install nodejs node -v ``` If you are using RHEL / CentOS, install or update NodeJS with this command: ``` curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo -E bash - sudo yum install -y nodejs node -v ``` ### 󠀁[Installing the Runner](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#installing-the-runner)󠁿 First, download the software. This example uses the `/home/wptestrunner/` folder, but set it to the best for this environment. ```bash cd /home/wptestrunner/ git clone https://github.com/WordPress/phpunit-test-runner.git cd phpunit-test-runner/ ``` The next step will be to configure the environment. To do this, make a copy of the example file and then configure it. ```bash cp .env.default .env vim .env ``` The content (in summary form) can be something like this: ```bash # Path to the directory where files can be prepared before being delivered to the environment. export WPT_PREPARE_DIR=/home/wptestrunner/wordpress # Path to the directory where the `wordpress-develop` repository can be copied, and from which tests can be run. When running tests in the same environment, set WPT_TEST_DIR to WPT_PREPARE_DIR export WPT_TEST_DIR=$WPT_PREPARE_DIR # API key to authenticate with the reporting service in 'username:password' format. Check the "Creating your bot" section on how to get your authentication. export WPT_REPORT_API_KEY= #export WPT_REPORT_API_KEY=examplehostingcompanybot:XXXX XXXX XXXX XXXX # (Optionally) define an alternate reporting URL export WPT_REPORT_URL= # Credentials for a database that can be written to and reset. WARNING!!! This database will be destroyed between tests. Only use safe database credentials. export WPT_DB_NAME=wordpress export WPT_DB_USER=wordpress export WPT_DB_PASSWORD=__PASSWORD__ export WPT_DB_HOST=localhost # (Optionally) set a custom table prefix to permit concurrency against the same database. export WPT_TABLE_PREFIX=${WPT_TABLE_PREFIX-wptests_} # (Optionally) define the PHP executable to be called export WPT_PHP_EXECUTABLE=${WPT_PHP_EXECUTABLE-php} # (Optionally) define the PHPUnit command execution call. Use if `php phpunit.phar` can't be called directly for some reason. export WPT_PHPUNIT_CMD= # (Optionally) define the command execution to remove the test directory. Use if `rm -r` can't be called directly for some reason. export WPT_RM_TEST_DIR_CMD= # SSH connection string (can also be an alias). Leave empty if tests are meant to run in the same environment. export WPT_SSH_CONNECT= # Any options to be passed to the SSH connection. Defaults to '-o StrictHostKeyChecking=no' export WPT_SSH_OPTIONS= # SSH private key, base64 encoded. export WPT_SSH_PRIVATE_KEY_BASE64= # Output logging. Use 'verbose' to increase verbosity export WPT_DEBUG= ``` Configure the folder where the WordPress software downloads and the database accesses will be made to prepare the tests. ### 󠀁[Preparing the environment](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#preparing-the-environment)󠁿 Before performing the first test, let’s update all the components. This process can be run before each test in this environment if you want to keep it up to date, although it will depend more on whether it is in a production environment. ```bash cd /home/wptestrunner/phpunit-test-runner/ git pull source .env ``` ### 󠀁[Preparing the test](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#preparing-the-test)󠁿 Now that the environment is ready, run the test preparation. ```bash php prepare.php ``` The system will run a long series of installations, configurations, and compilations of different elements in order to prepare the test. If warnings come out, you should not worry too much, as it is quite normal. At the end of the process, it will warn you if it needs something it doesn’t have. If it works, you should see something like this at the end: ``` Done. Replacing variables in wp-tests-config.php Success: Prepared environment. ``` Now that the environment has been prepared, the next step is to run the tests for the first time. All 4 steps must be executed every time a test is run. That includes the preparation of the environment by running `prepare.php` each time, even if no changes to the env configuration have been made. ### 󠀁[Running the test](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#running-the-test)󠁿 Now that the environment is ready, let’s run the tests. To do this, execute the file that will perform it. ```bash php test.php ``` What do the symbols mean? `.` Each dot means that the test has been passed correctly. `S` It means the test has been skipped. This is usually because these tests are only valid in certain configurations. `F` Means that the test has failed. Information about why this happened is displayed at the end. `E` It means that the test has failed due to a PHPPHP PHP (PHP: Hypertext Preprocessor) is a general-purpose scripting language especially suited to web development. PHP code is usually processed on a web server by a PHP interpreter. On a web server, the result of the interpreted and executed PHP code would form the whole or part of an HTTP response. error, which can be an error, warning, or notice. `I` Means that the test has been marked as incomplete. If you follow these steps, everything should work perfectly and you should not make any mistakes. If you encounter errors after following these steps, it may be due to some missing adjustment or extension of PHP, among others. We recommend that you adjust the configuration until it works correctly. After all, this tool is to help you improve the optimal configuration for WordPress in that infrastructure. ### 󠀁[Creating a report](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#creating-a-report)󠁿 Even if the test has failed, a report will be made. The first one shows the information about our environment. Among the most important elements are the extensions that are commonly used in WordPress and some utilities that are also generally useful. ```bash cat /home/wptestrunner/wordpress/env.json ``` The content of this file is somewhat similar to this: ```language-json { "php_version": "7.4.5", "php_modules": { "bcmath": false, "curl": "7.4.5", "filter": "7.4.5", "gd": false, "libsodium": false, "mcrypt": false, "mod_xml": false, "mysqli": "7.4.5", "imagick": false, "pcre": "7.4.5", "xml": "7.4.5", "xmlreader": "7.4.5", "zlib": "7.4.5" }, "system_utils": { "curl": "7.58.0 (x86_64-pc-linux-gnu) libcurl\/7.58.0 OpenSSL\/1.1.1g zlib\/1.2.11 libidn2\/2.3.0 libpsl\/0.19.1 (+libidn2\/2.0.4) nghttp2\/1.30.0 librtmp\/2.3", "ghostscript": "", "imagemagick": false, "openssl": "1.1.1g 21 Apr 2020" }, "mysql_version": "mysql Ver 15.1 Distrib 10.4.12-MariaDB, for debian-linux-gnu (x86_64) using readline 5.2", "os_name": "Linux", "os_version": "4.15.0-20-generic" } ``` In addition to this report, a definitive file with all the information on what happened in the tests will be provided. This is the one that includes all the tests that are made (more than 10,000), giving information on the time that they take to be executed and any problems that may have arisen. ```bash cat /home/wptestrunner/wordpress/junit.xml ``` At this point, we can generate the reports by sending them to WordPress.orgWordPress. org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. [https://wordpress.org/](https://wordpress.org/), if necessary. Even if you haven’t included the WordPress user (see below for how to create it), you can still run this file. ```bash php report.php ``` ### 󠀁[Cleaning up the environment for other tests](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#cleaning-up-the-environment-for-other-tests)󠁿 Having the tests working, all that remains is to delete all the files that have been created so that we can start over. To do this, execute the following command: ```bash php cleanup.php ``` ### 󠀁[Automating the execution](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#automating-the-execution)󠁿 Once this first manual test has been done, please automate all these steps in a script, since it is required that each of these steps is executed sequentially for each test execution. This script should be run every time there is a change / commit in the WordPress master. Many hosting companies use a cronCron Is a time-based job scheduler in Unix. Users that set up and maintain software environments use cron to schedule jobs to run periodically at fixed times, dates, or intervals. to run the script every few hours/days to make the appropriate checks, or when a change is made. ### 󠀁[Improving the configuration](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#improving-the-configuration)󠁿 Do not forget that this tool aims to verify that the environment and infrastructure are the optimal ones for WordPress to work, so, following the example, you could make several improvements, such as installing the extension of `bcmath`, `gd`, ` libsodium`, `mcrypt`, `mod_xml` and `imagick` or utilities such as `ghostscript` and `imagemagick`. The goal? To be error-free and have the green light for the perfect configuration. Some tests may be skipped, or there may be tests that PHPUnit considers “risky”. ## 󠀁[How to report: Creating your bot for WordPress.org](https://make.wordpress.org/hosting/handbook/tests/?output_format=md#how-to-report-creating-your-bot-for-wordpress-org)󠁿 If you / your company want the test [results to appear on the WordPress.org page](https://make.wordpress.org/hosting/test-results/), create a user for that. The first thing to do is [create a user on WordPress.org](https://login.wordpress.org/register). If your company is called _ExampleHostingCompany, Inc_, for example, call your user something like _examplehostingcompanybot_. Keep in mind that the associated email account should be checked frequently, as emails will arrive regarding the possible operation of the tests. Create [an issue on the test page](https://github.com/WordPress/phpunit-test-runner/issues/new?assignees=&labels=test-reporter-request&projects=&template=test_reporter_request.md&title=%5BTest+Reporter%5D+) asking to include the bot in the results page as a _Test Reporter_, indicating the email account you used with that user. The avatarAvatar An avatar is an image or illustration that specifically refers to a character that represents an online user. It’s usually a square box that appears next to the user’s name. of this user must be your company’s logo, and the name and URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org must make clear which company it is. Someone in the hostingHosting A web hosting service is a type of Internet hosting service that allows individuals and organizations to make their website accessible via the World Wide Web. team will review the request and add a user for you, or request additional information. The team will reply as quickly as possible, but as this step is manual, please be patient. Once the user has been created in the system, you’ll get an invitation to join via email. Then, you can log into make.wordpress.org/hosting and create an Application Password in Users -> Your Profile. To get things reporting properly, place the username for the bot, along with the application password, in the .env file, which will look something like this: `export WPT_REPORT_API_KEY='examplehostingcompanybot:ABCD 1234 abcd 4567 EFGH efgh'`. If you’re interested in improving this handbook, check the [Github Handbook repo](https://github.com/WordPress/hosting-handbook/), or leave a message in the [#hosting channel](https://wordpress.slack.com/archives/hosting/) of the official [WordPress Slack](https://make.wordpress.org/chat/). First published 2021-02-11 Last updated 2026-02-11 Edit article [ Improve it on GitHub: [article_title] ](https://github.com/wordpress/hosting-handbook/edit/main/tests.md) Changelog [ See list of changes: [article_title] ](https://github.com/wordpress/hosting-handbook/commits/main/tests.md) [ Previous: Upgrading WordPress](https://make.wordpress.org/hosting/handbook/upgrading/) [ Next: Learn Hosting](https://make.wordpress.org/hosting/handbook/learn-hosting/)