One of the great promises with the release of Magento 2 was that the core codebase would ship with unit tests built in so that you could have some way to be able to tell if you did something to break the site long before you ever pushed your code to production. In reality, though, since you should never directly edit the core files, instead only override their functionality, as a Magento 2 developer, there is little that you should be able to do that will cause the shipped tests to fail. Instead, the testing framework for unit tests makes it much easier for the extension developers and customizers to be able to unit test their custom code to ensure that the code does exactly what they expect it to.

However, if that were the end of the story, then there would be no need for this post. The Magento 2 Documentation on unit tests covers quite a bit about how to run them and setup new tests, however it is a bit lacking if you are looking to it to assist with troubleshooting the reasons that the tests may fail. In order to run the tests, you should only need to navigate to the Magento 2 root directory and run php bin/magento dev:tests:run unit and wait for the entire test suite of almost 22,000 tests to run to completion. However, if you don’t go through a few steps first, you will repeatedly see tests fail after 2,000 to 3,000 of the tests had finished with a nasty exception that stops the test runner from processing any more tests.

  1. Make sure that your site is setup to be in development mode by running php bin/magento deploy:mode:set developer.
  2. Clear the cache for the entire site. While the tests are supposed to be true ‘unit’ tests, in reality, there are some outside resources that seem to have an effect on the tests themselves. Clear the cache with php bin/magento cache:flush.
  3. This step is not one that I have run across anywhere else online, but was the only solution to fix the issues I was seeing with Magento 2.1.3 unit tests failing repeatedly and randomly. Empty the var/generation folder. You must repeat this after each time that you load any of the site in a web browser before running the unit tests. The code compilation process puts code here either all at once in production mode, or as you need it when in development mode. Clearing it out ensures that the unit tests will compile the php that is appropriate for the testing framework instead of what is needed for displaying the site.

Once you have performed these tasks, you should be able to run all 22,000 or so tests and have them finish in just a few minutes.