otgs/unit-tests-framework

A framework to build unit tests with OTGS products

PhpUnit

• Create a tests directory in your project
• Create a phpunit subdirectory in tests¹
• Copy samples/phpunit.xml file in the root of your project²
  • Change test-suite-name into something appropriated
  • Most likely, you won't need to change anything else in that file
• Copy samples/bootstrap.php into tests/phpunit
  • Read the comments in this file and make the appropriated changes
• Run composer require --dev otgs/unit-tests-framework³
• Create another tests subdirectory in tests/phpunit
  • Write your tests there
  • Unless you have customized the phpunit.xml file, you don't need to name the test files and classes in any particular way
• Run phpunit from your project's root to start your tests[^4]

How to use the OTGS_TestCase class

In order to take the most of this library, all your tests classes should extext OTGS_TestCase., _(*1)

Once you do that, this will happen:, _(*2)

1. \OTGS_TestCase::setupBeforeClass:
   • $_GET and $_POST are set to an empty array
   • An instance of FactoryMuffin is provided: you can refer to it as self::$fm (see "Resources and dependencies" for more details)
2. \OTGS_TestCase::setUp
   • FunctionMocker is initialized (see "Resources and dependencies" for more details)
   • WP_Mock is initialized (see "Resources and dependencies" for more details)
3. \OTGS_TestCase::tearDown
   • WP_Mock is destroyed
   • FunctionMocker is destroyed
   • Mockery is destroyed (just in case it has been used)
4. \OTGS_TestCase::tearDownAfterClass
   • Deletes all models created with FactoryMuffin

Mock WP Core functions

This class also provide an helper method to quickly mock the functions defined by WordPress by using the \OTGS_TestCase::get_mocked_wp_core_functions which returns an instance of OTGS_Mocked_WP_Core_Functions., _(*3)

OTGS_Mocked_WP_Core_Functions organize mocks in methods named using the same name of the file where the function is defined in WordPress codebase., _(*4)

For instance, to mock of all functions defined in post.php like get_post, in your test you should simply call $this->get_mocked_wp_core_functions()->post()., _(*5)

To mock add_query_arg yo call $this->get_mocked_wp_core_functions()->functions() because add_query_arg is defined in functions.php., _(*6)

OTGS_Mocked_WP_Core_Functions tries to handle dependencies., _(*7)

So, if you call $this->get_mocked_wp_core_functions()->post() to mock wp_insert_post, you automatically call $this->get_mocked_wp_core_functions()->post(), so to get all the meta related functions mocked as well.
Finally, there is a "mock all" method you could use (though is discouraged) with $this->mock_all_core_functions()., _(*8)

Stub WP common classes

\OTGS_TestCase provides a helpful way to quickly get a stub of some of the most commonly used classes in WordPress., _(*9)

By calling $this->stubs->wpdb() you will get a stub you can pass as a dependency of the classes you are testing. If you need to control the behavior of this stub, you just use the standard PHPUnit mock helpers., _(*10)

E.g. 1:, _(*11)

$wpdb = $this->stubs->wpdb();  
$wpdb->method( 'get_var' )->willReturn( 1 );

E.g. 2:, _(*12)

$results = array(
    array( 'translation_id' => 1, 'element_id' => 1, 'language_code' => 'en', 'source_language_code' => null, 'trid' => 1, 'element_type' => 'post_page' ),
    array( 'translation_id' => 2, 'element_id' => 2, 'language_code' => 'fr', 'source_language_code' => 'en', 'trid' => 1, 'element_type' => 'post_page' ),
);
$wpdb = $this->this->wpdb();
$wpdb->expects( $this->exactly( 2 ) )->method( 'get_results' )->willReturn( $results );

Other stubs you can get:, _(*13)

• WP_Widget with $this->stubs->WP_Widget()
• WP_Theme with $this->stubs->WP_Theme()
• WP_Filesystem_Direct with $this->stubs->WP_Filesystem_Direct()
• WP_Query with $this->stubs->WP_Query()

It is important to know that, if you only need the class to be defined (e.g. hard-dependency, or sub-classing), you don't need to assig the stub to a variable: just call the method., _(*14)

A good example is with WordPress' widgets, where you may have your own widget which is supposed to extend WP_Widget., _(*15)

In this case, unless you want to mock some of the WP_Widget methods, you simply call $this->stubs->WP_Widget(), then write your tests.
The class which extends WP_Widget will find a definition of this class, with all the methods (doing nothing)., _(*16)

Resources and dependencies

Below are some resources on writing unit tests which lead to the creation of this library and links to the libraries included here:, _(*17)

• Start from here for a general explanation: http://wordpress.stackexchange.com/a/164138/7291
• 10up's WP_Mock`: https://github.com/10up/wp_mock
• Mockery: https://github.com/padraic/mockery
• Function mocker: https://github.com/lucatume/function-mocker
• Factory Muffin: https://github.com/thephpleague/factory-muffin
• Factory Muffin Faker: https://github.com/thephpleague/factory-muffin-faker
• The DomCrawler Component: http://symfony.com/doc/current/components/dom_crawler.html
• The CssSelector Component: http://symfony.com/doc/current/components/css_selector.html
• php-loremipsum: https://github.com/joshtronic/php-loremipsum