Testing Quick-Start Guide

Unit Tests

Until the documentation is in full effect, it’s recommended that a GraphiQL-based tool like WPGraphQL IDE be used to view the GraphQL schema, an alternative to this is viewing the unit tests located in tests/wpunit directory. Which are constantly updated along with the project. If you’re interested in contributing when I begin accepting contributions or simply want to run the tests. Follow the instruction below.

Prerequisites

Setup

  1. First copy the .env.testing file as .env
  2. Next open .env and alter for your usage.
  • Typical you should only have to change the WordPress database configurations to use local testing.
  1. Once you have finished modifying the .env file. Run composer install-test-env from the project directory. This will install WordPress + Codeception w/ WPBrowser, as well as set up the database if needed.
  2. Upon success, you can begin running the tests.

Running tests locally

To run the tests use the command vendor/bin/codecept run [suite [test [:test-function]]]. If you use the command with at least a suite specified, Codeception will run all tests, however, this is not recommended. Running a suite vendor/bin/codecept run wpunit or a test vendor/bin/codecept run CouponQueriesTest is recommended. Running a single test-function like vendor/bin/codecept run ProductQueriesTest:testProductsQueryAndWhereArgs is also possible.

To learn more about the usage of Codeception with WordPress view the Documentation

Functional and Acceptance Tests (Server or Docker required)

Running functional and acceptance tests requires that the WordPress installation being used for testing be accessible thru some kind of URL/Address and then setting that URL/Address in the codeception.dist.yml file or in the .env file as WORDPRESS_DOMAIN/WORDPRESS_URL.

Note: The codeception.dist.yml should be left unchanged and a copy named codeception.yml should be used.

Running the install-test-env alone does not configure a server to point at the WordPress installation it creates, you’re two options for doing this.

  1. Configure an Apache or Nginx server block and point it at the WordPress installation created by the install-test-env script. This isn’t a very flexible or quick method.
  2. Use the Docker configurations in the project to push the installation into a docker network and expose its docker container’s IP as the URL/Address. This is the recommended option if Docker/Docker-Compose is available to you. The project includes some simple composer scripts that enable you to run all at once or filter specific tests for speed, test isolation, or XDebug Stepping Debug.

The composer scripts for using dockers are.

  • docker-build builds this the Docker Image for the woographql/wordpress container that will house the WordPress installation and tests.
  • docker-run-app spins up the docker network. This can be used for live debugging as well as tests. The WordPress installation will be accessible from a URL provided in the woographql/wordpress container logs in your terminal.
  • docker-run-testing-db add a cloned MySQL instance of the one created docker-run-app for testing, this is to be run after the docker network has been created using docker-run-app and before the tests are run inside of the woographql/wordpress container. Note: This should not be used directly. See docker-run-test below.
  • docker-set-main-db configures the wp-config.php of WordPress installation to point at the main MySQL container. This is for returning to live development using the browser after running the tests in CLI.
  • docker-set-testing-db is essentially the same docker-set-main-db just for the testing database. However this script stalls and looks for the testing database to be available. Note: This should not be used directly. See docker-run-test below.
  • docker-run-test is the primary tester script and the script you’ll probably call the most. This script essentially just runs codecept run $FILTER in the woographql/wordpress, however before that it runs docker-run-testing-db, and docker-set-testing-db to ensure all the needed players are set. FILTER is a shell variable that can be what parameter you what to pass to the run command except the --env or --no-exit options. For usage see this example. FILTER="wpunit CartMutationsTest:testAddToCartMutationWithProduct --debug" composer docker-run-test
  • docker-run-test-standalone setups the docker network runs all the tests and pulls down the network. Primarily for CI.

Running tests with Docker/Docker-Compose

Running the tests is rather simple, but you may need two terminal windows depending on your method.

  • (Requires two terminals in the project root directory) In one terminal run composer docker-build && composer docker-run-app. Wait until you see the log testable_app_x_xxxxxxxxxxxx | WordPress app located at http://xxx.xxx.xxx.xxx, then you’re ready to run the tests and can leave this terminal running and move to your second one. In your second terminal, you can run the by executing the composer run-test. This will run all the tests at once with no options passed to the concept run command. This can be altered with FILTER variables mentioned in the last section. The first time you run this command it will be delayed due to having to set up the test database. Also, one last thing to note is if you want to switch to live development/debugging in the browser have run the test this way. Run composer docker-set-main-db before you do.
  • This other method is even a lot more streamlined and only needs one command composer docker-run-test-standalone. See the description of what it does in the last section.

Using docker-compose to run a local installation for live testing

This is rather simple just like with testing using docker ensure that env.dist and codeception.dist.yml are untouched.

  1. Run composer docker-build && composer docker-run-app.
  2. Wait until you see the log testable_app_x_xxxxxxxxxxxx | WordPress app located at http://xxx.xxx.xxx.xxx.
  3. Navigate to the provided address.
Previous: Local Testing