Testing

This wiki page provides you with our testing processes, quick start and setup, and our best practices.

Links

• Quick Start
• Overview

Quick Start

1. Tests are required.
2. Beans has 2 types of tests baked into it:
   • unit tests - standalone unit tests that test single functionality without WordPress. We use Brain Monkey in our unit tests to monkey patch WordPress functions on a test-by-test basis.
   • integration tests - tests run with WordPress
3. Everything you need to write and run tests in baked into the development version. Refer to the Quick Start Setup Guide to get it installed and setup.
4. To run tests, do the following in your favorite command line app:
   • Unit tests - type: composer tests-unit
   • Integration tests - type: composer tests-integration

Overview

Our Guiding Principle: Test. Test. Test.

Our guiding principle is:

ALL functionality will be fully unit tested. Period. Integration tests are optional, except as noted in this wiki.

Why?

Testing serves multiple purposes including:

1. It ensures a release candidate and release is stable. Hint: That's a guiding principle.
2. It ensures that each piece of the code is performing as designed, intended, and expected.
3. Testing flushes out vulnerabilities, wonky behavior, side-effects, and assumptions. Seriously, I can't tell you how many times I've designed something, ran the tests, and realized I had an issue I hadn't considered.
4. Tests are a great way to discover how some piece of code works in the codebase. I usually start with the test suite to understand a new framework, app, or tool. It quickly shows me how to implement the functionality and how it should behave.
5. When we make changes (and we will), tests assure us that our change works and doesn't break another area in Beans.
6. If it worked before you made the change, a failing test helps you to sniff out the root cause.

Okay, did I convince you? I hope so. I'll be building testing labs on Know the Code to walk you through the entire process A-to-Z.

Types of Tests

Testing has multiple levels to it, each of which serves a different purpose and adds a layer of assurance to the project's stability and code coverage.

1. Single unit tests (without WordPress)
2. Integration tests (WordPress runs)
3. Live single website testing on your local machine
4. Live multisite testing on your local machine
5. Alpha testing
6. Beta testing

There are other forms of testing, including Usability Tests. We'll focus on 1-4 above.

Need Help?

Reach out on Slack in the #contribute group. We are here to help you contribute to Beans! And don't worry. ALL QUESTIONS should be asked. If you're wondering, someone else is too.

Single Unit Tests (without WordPress)

A core principle of testing is to test in isolation. Have you heard that phrase before? It means that you are testing a single unit and not the framework, language, application, etc. Huh? You are testing the functionality within a function or method, i.e. one single function.

I can hear your doubts and questions. Stick with me.

WordPress gives us a lot of functionality that we use throughout Beans. Right? Things like add_action, add_filter, get_the_ID(), and so on. We need these functions.

However, when we're testing our code, we expect these functions to behave and give us some value or do something for us. We are not testing WordPress Core. Nope. The Core team and contributors build tests for Core. Not us.

In our tests, we assume and expect that when we call get_the_ID(), we get the ID.

Using monkey patching, which is also called to mock a dependency, we can jump around code that is not in Beans, such as WordPress Core functions.

What happens is: WordPress never runs when unit testing. Instead, using the command line, we run our tests by typing: composer test-unit. Everything we need loads and runs, test-by-test.

How do we mock or monkey patch?

We have standardized on Brain Monkey by Giuseppe Mazzapica. Brain Monkey gives us the means to mock any functionality we want.

What happens? WordPress never runs. Our unit tests test only our code. That's it. We can then focus our energies on the quality, performance, and functionality of our stuff.

When are Unit Tests Needed?

They are almost always needed across the board. Rarely though is a codebase 100% tested and has full code coverage. We will strive for 90% and keep pushing for full coverage.

A rule of thumb: Test it and submit your tests with your PR.

How to run the unit tests?

You'll need access to a command line tool, like Terminal (Mac), the one built into PhpStorm, or others.

1. In the command line app, navigate to the Beans theme directory.
2. Then type:

composer test-unit

3. Press return/enter.

The unit test will run and give you a report of what passed and failed. Failures are listed for you to check your code.

Integration Tests (With WordPress)

An integration test means that we are integrating a third-party dependency(ies) to run with our code in order to test the application's functionality. In other words, it tests how does everything run together in a testing environment.

To do this, you would need to install and set up the WordPress Automated Testing Suite. Instructions are found here for PHP and here for JavaScript.

If you've contributed to WordPress Core or some theme/plugin that uses these automated tests, then you are likely already set up and ready to go.

When are Integration Tests Needed?

Integration tests are handy when you need to test the sequence and interactivity between all the dependencies, but you want to do it in an automated, controlled fashion.

You might be thinking: "Hey, I can just run the website on my local machine and manually test." (You were thinking that, weren't you? LOL). Well, there's a problem. We are not good at sniffing out every single interaction, received response, and so on. We want to run tests at the granular level where we can get a report that tells us the details.

Some examples of integration testing areas are:

• Authentication
• Templates
• The Loop
• Menu structures
• Commenting
• etc.

In other words, those areas where our code is heavily dependent upon WordPress doing its thang and then calling us at the right time.

Bottomline: We first do our single unit test per function. Then we build the needed integration tests to test timing and interactivity.

Live single website testing on your local machine

We all manually test in the wild by running the website and seeing what happens. Right? This technique is valid and extremely helpful once we've completed the single unit tests and integration tests. Now it's time to run the website for real and try to break it.

In the "single" website local tests, you have a standalone website, i.e. not multisite. It's running on your machine. You have the latest version of a Beans' branch that you want to test.

1. Turn on Debug mode.
2. Run the site and try to break it.
3. Monitor the web server logs (depending upon which localhost app you're using, those logs could be in different places).
4. If you find something weird, stop and analyze. Try to recreate it. Look at the contributing factors. Try to find the root cause. If it requires a change in the code, then adjust the unit and integration tests. Repeat.

Live multisite testing on your local machine

Beans can run on both standalone and multisite sites. Using your localhost web server app, create 2 multisites: (1) for a subdirectory mu and (2) the other for subdomain mu.

Just like with the single standalone live test above, repeat the process for each of the sub-sites. Try to break it. If you do, figure out why, what's the root cause, and then fix the problem. Repeat.

Writing Unit Tests

I love writing unit tests. I do. I'm an avid TDD (Test-Driven-Development) workflow engineer.

.......more to come here.......