SpecBundle © Lukas Botsch

Content

• Introduction
• Install
• Prerequisits
• Getting the code
• Manual installation
• Writing Specs
• Using the console
• Example Spec class
• Predefined actions
• GIVEN
• WHEN
• THEN
• Writing custom actions

Introduction

Install

Prerequisits

SpecBundle builds on PHPUnit and requires PHPUnit (3.5) The recommended way to install PHPUnit is by using PEAR Read the excelent documentation: http://www.phpunit.de/manual/current/en/installation.html

Getting the code

Manual installation

• Copy the SpecBundle/ directory into your projects src/Bundle directory.
• Edit your app/AppKernel.php file and register the bundle public function registerBundles() { $bundles = array( ... // register your bundles new Bundle\SpecBundle\SpecBundle(), // Register the SpecBundle ... ); ... }

Writing Specs

Using the console

SpecBundle adds the command init:spec to the symfony command line tool. You can use it to initialize a new Spec definition for your bundle. It will generate a Spec for a simple CRUD interface.

Read the manual page for instructions:

app/console --help init:spec

Example Spec class

class SymfonySpec extends SymfonySpecBase
{
    /**
     * @scenario
     */
    public function masterSymfony() {
        $this->given('You don\'t know Symfony')
             ->when('You get started with it')
             ->then('You will never want anything else and eventually become MASTER OF SYMFONY');
    }
}

The SymfonySpec class extends SymfonySpecBase. You can find the base class in the Tests/Spec/Base/ subdirectory of your bundle. In there you can add your custom actions. Read more about custom actions in the Write custom actions section.

Inside the SymfonySpec class, you define scenarios as methods. You have to annotate your scenario methods with @scenario. Inside your scenario, you can use the simple DSL exposed by the spec API.

As SpecBundle uses the PHPUnit Story extension, you can have a look at the documentation to get an overview of its functionality.

From the documentation:

The PHPUnit_Extensions_Story_TestCase class adds a story framework that faciliates the definition of a Domain-Specific Language for Behaviour-Driven Development. Inside a scenario, given(), when(), and then() each represent a step. and() is the same kind as the previous step. The PHPUnit_Extensions_Story_TestCase class adds a story framework that faciliates the definition of a Domain-Specific Language for Behaviour-Driven Development. Inside a scenario, given(), when(), and then() each represent a step. and() is the same kind as the previous step. The following methods are declared abstract in PHPUnit_Extensions_Story_TestCase and need to be implemented:

• runGiven(&$world, $action, $arguments)
• runWhen(&$world, $action, $arguments)
• runThen(&$world, $action, $arguments)

As your Specs inherit from PHPUnit_Extensions_Story_TestCase, you can follow the instructions from the PHPUnit documentation and implement the above methods to declare your DSL. But SpecBundle already implements its own DSL that you can use and extend as you need. You will learn more about the built-in actions in the Predefined Actions section.

The masterSymfony scenario uses three types of steps: given, when and then.

• given describes the initial world: You don't know Symfony
• when describes the action that is made to the world: You learn Symfony
• then describes the final state of the world: You master Symfony

Now read about the built-in actions to be able to write some useful specs ;)

Predefined Actions

SpecBundle has some built-in actions you can use to define your specs. Each step type has a number of useful built-in actions:

GIVEN: The initialization

• Default context: Initializes your application kernel and a web client instance is saved to $world["client"].

  Arguments:

  • array Options

  The following options are passed to the kernel
  
  -    'env'      => The environment to run in
  -    'debug'    => Enable debugging
  
  Anything else is passed to the client as SERVER options (_see $\_SERVER_)
  

  Example:

  ->given('Default context', array(
      'env' => 'test',
      'HTTP_SERVER' => 'localhost',
      'HTTP_USER_AGENT' => 'spectest client v1.0',
  ))
  

WHEN: The interaction

• Go to page: Uses the client if initialized in the GIVEN section to make a request to a given url and saves a dom crawler for the requested page in $world["crawler"].

  Arguments:

  • string URL to navigate to
  • string HTTP method (defaults to 'GET')
  • array (optional) POST data in name => value format

  Example:

  ->when('Go to page', '/home')
  

• Click link: Finds a link in the current page and clicks on it Arguments:

  • array Locator options for the link
    • 'label' => (regex) Tries to find a link by its content
    • 'id' => (string) Find a link by its id
    • 'css' => (string) Find a link using a css locator
    • 'xpath' => (string) Find a link using xpath

  Example:

  ->when('Click link', array(
      'css' => 'a#my-link',
  ))
  

• Fill form: Fills in a form and submits it

  Arguments:

  • array Locator options for the form
    • 'label' => (regex) Tries to find a form by its content
    • 'id' => (string) Find a form by its id
    • 'css' => (string) Find a form using a css locator
    • 'xpath' => (string) Find a form using xpath
  • array Fields
    • 'name' => (string) Tries to find a form field by its name
    • 'label' => (regex) Tries to find a form field by its label
    • 'id' => (string) Find a form field by its id
    • 'css' => (string) Find a form field using a css locator
    • 'xpath' => (string) Find a form field using xpath
    • 'value' => (string or bool) The fields value (use bool for checkbox)
  • bool Submit the form (Defaults to true)

  Example:

  ->when('Fill form', array(
      'css' => 'form#my-form',
  ), array(
      array('name' => 'name', 'value' => 'Lukas'),
      array('name' => 'email', 'value' => 'lukas{DOT}botsch[AT]gmail{DOT}com'),
  ), true)
  

THEN: The checking

Writing custom actions

The built-in actions are useful to get you started in writing specs for your applications and bundles. However, you will most certainly want to write your own actions at some point. Thankfully, this is very easy with SpecBundle.