Introducing SilverStripeExtension for Behat

During the second phase of GSoC an idea came into my mind. Why not allow other developers test their SilverStripe modules behaviourally?

There was already an extension created for basic interactions with the temporary database, but it was not in the state where you would be able to use it outside of the Sapphire framework.

But that’s the thing of the past. Now, let me introduce you to the new, shiny SilverStripeExtension.

What can I do?

SilverStripeExtension is very simple, bootstrapping tool. It is only responsible for the following twothree tasks:

  1. It handles temporary database by creating and deleting it.
  2. It sets up file to URL mapping.
  3. Bootstraps SilverStripe classes so they are autoloaded when needed.

What it doesn’t do is that it neither will connect to the temporary database for you nor create any records in there. It’s your job.

Where do I get it?

SilverStripeExtension is available as a composer dependency. You can check out the details on packagist site. To have it available in your code make sure to add "behat/silverstripe-extension": "*" to your composer.json file. It is dependent on MinkExtension, but it’s been already taken care of for you.

How do I set it up?

Configuration is pretty straightforward. There are two options available, framework_path that is used in file to URL mapping and ajax_steps that is used to mark steps as AJAX steps (for special treatment).

Your FeatureContext has to implement SilverStripeAwareContextInterface. This interface has two methods available: setDatabase and setAjaxEnabledSteps. The former passes a temporary database name to your context while the latter passes an array of partial names of AJAX steps that are matched to apply special AJAX treatment.

Here’s how the extension is configured in SilverStripe Behaviour Testing Framework. We have behat directory put in framework/tests/behat, hence ../../ as framework path.

default:
  extensions:
    Behat\SilverStripeExtension\Extension:
      framework_path: ../../
      ajax_steps:
        - go to
        - follow
        - press
        - click
        - submit

Make sure to also configure MinkExtension’s base_url parameter as SilverStripeExtension needs it.

How do I connect to temporary database?

Good question! We have added a special /dev/tests/setdb TestRunner endpoint that does the trick. If you don’t know what TestRunner is, read about Unit and Integration Testing in SilverStripe. The endpoint expects a temporary database name as a database GET parameter.

In Behaviour Testing Framework, we do this before every scenario:

    /**
     * @BeforeScenario
     */
    public function before(ScenarioEvent $event)
    {
        if (!isset($this->database_name)) {
            throw new \LogicException('Context\'s $database_name has to be set when implementing SilverStripeAwareContextInterface.');
        }
 
        $setdb_url = $this->joinUrlParts($this->getBaseUrl(), '/dev/tests/setdb');
        $setdb_url = sprintf('%s?database=%s', $setdb_url, $this->database_name);
        $this->getSession()->visit($setdb_url);
    }

Where $this->database_name is variable that is set using what’s passed to the required setDatabase method.

How to deal with fixtures and assets?

Take a look at the SilverStripeContext we use at our Behaviour Testing Framework. You can find a special step there that loads fixtures into database: @Given /^there are the following ([^\s]*) records$/. It will also detect fixtures that are assets and will handle them accordingly. Assets management requires MinkExtension’s files_path parameter to be set.

How do I report issues?

Please report issues on silverstripe-behat-extension on github.

Is that it?

Yes, have fun!

Leave a Reply