WPBootstrapper module

Just bootstrapping WordPress in tests.

Good advice

About a week ago a discussion between me and GitHub user LeRondPoint began about the possibility to simply load a WordPress installation in an acceptance or functional test.
At the time I could see no case where this might be useful or where the same result might not be covered by the WPDb module.
I came across such a case today and took the time to develop a new module for the wp-browser Codeception add-on to do the job.

The use case

Tests, be it unit, functional or acceptance, will require a common start point to have any meaning.
This is referred to as “pre-conditions” or “fixture” and while it might require a few lines of code in a unit test it could require more effort, and maintenance, in an acceptance test.
So much effort that a common starting point for acceptance testing is the use of a database dump.
Database dumps are a good solution but not one that’s always applicable in WordPress testing: WordPress will store hard-coded URLs in the database and my local testing address will be different from the one used in another team member local set up.
Furthermore database dumps are difficult to maintain and not very ablative: what’s changing in the database when loading a database dump is not easily readable and comprehensible. Database dumps are meant to be machine-readable, not human-readable as code.
Sometimes a database dump will simply not make it or make it with a wasted maintenance effort.
Say I need to test that a certain JavaScript based interaction with a page will correctly update the URL appending the needed query vars (URL writing) and that reloading the page using that same URL will yield the expected results (URL reading).
In essence I’m saving the state in the URL and want to make sure it’s properly parsed.
And I need to test such a behaviour against all of WordPress default rewrite structures.
WordPress default rewrite structures

WordPress will rewrite URLs to queries matching the URL against a list that’s stored, for performance purposes, in the database.
That option in the database is updated when the permalink structure is changed and someone will “Save Changes” on the Permalinks Settings screen.
On the back-end the flush_rewrite_rules function will be called and the rewrite_rules option will be rebuilt.
This means that if I had to emulate that permalink structure change in a test, a Cest type test for example, I’d have to have a database dump for each ready or could use the WPDb module to set the permalink_structure option in the database; rewrite rules would not, though, be rebuilt with the new permalink structure.
Ideally being able to call flush_rewrite_rules in acceptance tests would make it all very easy.

Bootstrapping WordPress in acceptance tests

Without going into the details of the WPBootstrapper module this is an acceptance test I could have not written yesterday and can write today leveraging the only (for the moment) method the WPBootstrapper module will supply

class Issue_38042_Dropping_CategoryCest {

    protected $plugin = 'my-plugin/my-plugin.php';

    public function _before(AcceptanceTester $I) {
        // this is a WPDb module supplied method
        $I->haveOptionInDatabase('active_plugins', [$this->plugin]);

        $I->bootstrapWp();

        // I can now use WordPress functions!
        activate_plugin($this->plugin);
    }

    public function _after( AcceptanceTester $I ) {
        deactivate_plugin($this->plugin);
    }

    public function will_work_with_postname_structure(){
        update_option('permalink_structure', '/%postname%/');
        flush_rewrite_rules();

        // do some testing here...
    }

    public function will_work_with_archives_structure(){
        update_option('permalink_structure', '/archives/%post_id%');
        flush_rewrite_rules();

        // do some testing here...
    }

}

The decoupling is strong in this one!

I appreciate your input