DataSift\Storyplayer\PlayerLib\Story

Complexity

Total Complexity

99

Size/Duplication

Total Lines	1259
Duplicated Lines	0 %

Coupling/Cohesion

Components	6
Dependencies	5

Importance

Changes

0

77 Methods

Rating	Name	Duplication	Size	Complexity
A	inGroup()	0	10	2
A	generateGroup()	0	15	1
A	called()	0	6	1
A	generateName()	0	6	1
A	getCategory()	0	4	1
A	setCategory()	0	5	1
A	getGroup()	0	4	1
A	getGroupAsString()	0	4	1
A	setGroup()	0	5	1
A	getName()	0	4	1
A	setName()	0	5	1
A	setParams()	0	5	1
B	getParams()	0	28	4
A	determineStoryFilename()	0	5	1
A	getStoryFilename()	0	4	1
A	addValidRole()	0	4	1
A	andValidRole()	0	4	1
A	hasRole()	0	4	1
A	getRoleChanges()	0	4	1
A	hasRoleChanges()	0	4	1
A	setRoleChanges()	0	4	1
F	basedOn()	0	24	13
A	getStoryTemplates()	0	4	1
A	getRequiredStoryplayerVersion()	0	4	1
A	requiresStoryplayerVersion()	0	5	1
A	runsOn()	0	5	1
A	andOn()	0	5	1
A	getWhitelistedEnvironments()	0	4	1
A	requiresTestEnvironmentWithRoles()	0	4	1
A	getRequiredTestEnvironmentRoles()	0	4	1
A	getPersistDevice()	0	4	1
A	setPersistDevice()	0	5	1
A	getTestCanRunCheck()	0	4	1
A	hasTestCanRunCheck()	0	4	1
A	addTestCanRunCheck()	0	4	1
A	setTestEnvironmentSetup()	0	4	1
A	addTestEnvironmentSetup()	0	4	1
A	setTestEnvironmentTeardown()	0	4	1
A	addTestEnvironmentTeardown()	0	4	1
A	getTestSetup()	0	4	1
A	hasTestSetup()	0	4	1
A	addTestSetup()	0	4	1
A	getTestTeardown()	0	4	1
A	hasTestTeardown()	0	4	1
A	addTestTeardown()	0	4	1
A	getPerPhaseSetup()	0	4	1
A	hasPerPhaseSetup()	0	4	1
A	addPerPhaseSetup()	0	4	1
A	getPerPhaseTeardown()	0	4	1
A	hasPerPhaseTeardown()	0	4	1
A	addPerPhaseTeardown()	0	4	1
A	getDeviceSetup()	0	4	1
A	hasDeviceSetup()	0	4	1
A	addDeviceSetup()	0	4	1
A	getDeviceTeardown()	0	4	1
A	hasDeviceTeardown()	0	4	1
A	addDeviceTeardown()	0	4	1
A	getHints()	0	4	1
A	hasHints()	0	4	1
A	setHints()	0	4	1
A	addHints()	0	4	1
A	getPreTestPrediction()	0	4	1
A	hasPreTestPrediction()	0	4	1
A	addPreTestPrediction()	0	4	1
A	getPreTestInspection()	0	4	1
A	hasPreTestInspection()	0	4	1
A	addPreTestInspection()	0	4	1
A	addAction()	0	4	1
A	addActions()	0	4	1
A	getOneAction()	0	14	2
A	hasActions()	0	4	1
A	getPostTestInspection()	0	4	1
A	hasPostTestInspection()	0	4	1
A	addPostTestInspection()	0	4	1
B	setDefaultCallbacks()	0	45	5
A	__toString()	0	4	1
A	getResult()	0	8	2

<?php

/**
 * Copyright (c) 2011-present Mediasift Ltd
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 *   * Redistributions of source code must retain the above copyright
 *     notice, this list of conditions and the following disclaimer.
 *
 *   * Redistributions in binary form must reproduce the above copyright
 *     notice, this list of conditions and the following disclaimer in
 *     the documentation and/or other materials provided with the
 *     distribution.
 *
 *   * Neither the names of the copyright holders nor the names of his
 *     contributors may be used to endorse or promote products derived
 *     from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 *
 * @category  Libraries
 * @package   Storyplayer/PlayerLib
 * @author    Stuart Herbert <stuart.herbert@datasift.com>
 * @copyright 2011-present Mediasift Ltd www.datasift.com
 * @license   http://www.opensource.org/licenses/bsd-license.php  BSD License
 * @link      http://datasift.github.io/storyplayer
 */

namespace DataSift\Storyplayer\PlayerLib;

use Exception;

/**
 * Object that represents a single story
 *
 * @category  Libraries
 * @package   Storyplayer/StoryLib
 * @author    Stuart Herbert <stuart.herbert@datasift.com>
 * @copyright 2011-present Mediasift Ltd www.datasift.com
 * @license   http://www.opensource.org/licenses/bsd-license.php  BSD License
 * @link      http://datasift.github.io/storyplayer
 */
class Story
{
    /**
     * the category that this story belongs to
     * @var string
     */
    protected $category;

    /**
     * the group that this story belongs to
     * @var array<string>
     */
    protected $group;

    /**
     * the name of this story
     * @var string
     */
    protected $name;

    /**
     * the function that provides hints about how this story changes
     * the state of the system or user
     *
     * @var callable
     */
    protected $hintsCallback;

    /**
     * the function that checks to see if the test should run at all,
     * or should be skipped
     *
     * @var array
     */
    protected $testCanRunCheckCallback = array();

    /**
     * the function that provides any story-specific setup work
     *
     * @var array
     */
    protected $testSetupCallback = array();

    /**
     * the function that provides any story-specific teardown action
     * @var array
     */
    protected $testTeardownCallback = array();

    /**
     * the function that provides any story-specific setup work that
     * happens before each phase of the test
     * @var array
     */
    protected $perPhaseSetupCallback = array();

    /**
     * the function that provides any story-specific teardown work that
     * happens at the end of each phase of the test
     * @var array
     */
    protected $perPhaseTeardownCallback = array();

    /**
     * the function that provides any story-specific setup work that
     * happens when we start a device
     * @var array
     */
    protected $deviceSetupCallback = array();

    /**
     * the function that provides any story-specific teardown work that
     * happens just before we stop a device
     * @var array
     */
    protected $deviceTeardownCallback = array();

    /**
     * the function that provides information about how this story has
     * changed the state of the system or user
     *
     * @var array
     */
    protected $roleChangesCallback = array();

    /**
     * the callback that dynamically determines in advance whether the
     * story actions should succeed or fail
     *
     * @var array
     */
    protected $preTestPredictionCallback = array();

    /**
     * the callback that dynamically determines afterwards whether or not
     * the story actions actually did succeed
     *
     * @var array
     */
    protected $reportTestResultsCallback = array();

    /**
     * the callback used to remember the state of the system *before*
     * the action occurs
     *
     * @var array
     */
    protected $preTestInspectionCallback = array();

    /**
     * the callback used to see if the action *did* change the state of
     * the system under test
     *
     * @var array
     */
    protected $postTestInspectionCallback = array();

    /**
     * the actions that execute the story on behalf of the user
     *
     * this is an array of callbacks.  Each callback is a single set of
     * actions to execute the story.  Each callback is an alternative way
     * to execute the story.  Each callback is meant to be equivalent; ie
     * they achieve the same thing, just in different ways.
     *
     * If any of the callbacks has different outcomes, then they belong
     * in separate user stories. NO EXCEPTIONS. This is a fundamental
     * assumption of Storyplayer; ignore it, and Storyplayer's no use to
     * you!
     *
     * @var array
     */
    protected $actionsCallbacks = array();

    /**
     * a list of the StoryTemplates that this story is based on. can be
     * empty
     *
     * @var array
     */
    protected $storyTemplates = array();

    /**
     * the parameters that get passed into virtual machines et al, and
     * which can be overridden on the command-line
     *
     * @var array
     */
    protected $params = array();

    /**
     * the environments that a story states it runs on
     *
     * by default, a story is allowed to run on all environments, *but*
     * if an environment's config sets 'mustBeWhitelisted' to TRUE, then
     * the story is only allowed to run on that environment if the story
     * declares itself safe to run
     *
     * we believe that this is the safest approach to handling those
     * stories that simply aren't safe to run absolutely everywhere
     */
    protected $whitelistedEnvironments = array();

    /**
     * the raw parser tree of this story, and of any templates that we
     * use
     *
     * @var array
     */
    protected $parserTrees = array();

    /**
     * the file that contains the story
     *
     * @var string
     */
    protected $storyFilename = '';

    /**
     * a list of the roles that the test environment must have defined,
     * otherwise we cannot run
     *
     * @var array
     */
    protected $requiredTestEnvRoles = array();

    /**
     * does the story want the test device kept open between phases?
     *
     * @var boolean
     */
    protected $persistDevice = false;

    /**
     * which version of Storyplayer is this test written for?
     *
     * you HAVE to set this in your story, otherwise we will skip your
     * story
     *
     * @var integer
     */
    protected $compatibleVersion = 1;

    /**
     * what happened to this story?
     * @var \DataSift\Storyplayer\PlayerLib\Story_Result
     */
    protected $storyResult = null;

    // ====================================================================
    //
    // Metadata about the story itself
    //
    // --------------------------------------------------------------------

    /**
     * which group of tests does this story belong to?
     *
     * @param  array|string $groupName
     *         the group to use
     * @return Story
     *         $this for fluent interface
     */
    public function inGroup($groupName)
    {
        if (!is_array($groupName)) {
            $parts = explode(" > ", $groupName);
            $groupName = $parts;
        }
        $this->setGroup($groupName);

        return $this;
    }

    /**
     * Set the group name as the file system path of the directory where the test is located
     *
     * @return Story
     *         $this for fluent interface
     */
    public function generateGroup()
    {
        // Get the directory path
        $path = ltrim(
            str_replace(getcwd(), '', $this->getStoryFilename()),
            DIRECTORY_SEPARATOR
        );
        $directories = explode(DIRECTORY_SEPARATOR, $path);

        // Remove the base directory at the beginning and story file at the end of the path
        $groupName = array_splice($directories, 1, count($directories) - 2);
        $this->setGroup($groupName);

        return $this;
    }

    /**
     * @return Story
     */
    public function called($userStoryText)
    {
        $this->setName($userStoryText);

        return $this;
    }

    /**
     * Set the name as the filename of the test
     *
     * @return Story
     *         $this for fluent interface
     */
    public function generateName()
    {
        $this->setName(basename($this->getStoryFilename()));

        return $this;
    }

    /**
     * Get the category that this story belongs to
     *
     * Systems under test can grow to encompass hundreds, if not thousands
     * of user stories.  To make this manageable at scale, we break down
     * each user story like this:
     *
     * Name    : Starts as a free user with 10 USD in credit
     * Category: Billing User Stories
     * Group   : User States
     *
     * The 'name' is the summary text of the user story itself, which
     * should be no longer than a single sentence, please.
     *
     * The 'category' is the general group that the user story belongs to.
     * These are the top-level groups, such as 'Registration', 'Billing'
     * and so forth.
     *
     * The 'group' is the specific group _inside_ the category that the
     * user story belongs to.  The groups are specific to the category.
     *
     * @return string the category that this story belongs to
     */
    public function getCategory()
    {
        return $this->category;
    }

    /**
     * Set the category that this story belongs to
     *
     * Systems under test can grow to encompass hundreds, if not thousands
     * of user stories.  To make this manageable at scale, we break down
     * each user story like this:
     *
     * Name    : Starts as a free user with 10 USD in credit
     * Category: Billing User Stories
     * Group   : User States
     *
     * The 'name' is the summary text of the user story itself, which
     * should be no longer than a single sentence, please.
     *
     * The 'category' is the general group that the user story belongs to.
     * These are the top-level groups, such as 'Registration', 'Billing'
     * and so forth.
     *
     * The 'group' is the specific group _inside_ the category that the
     * user story belongs to.  The groups are specific to the category.
     *
     * @param  string $newCategory the category that this story belongs to
     * @return Story  $this
     */
    public function setCategory($newCategory)
    {
        $this->category = $newCategory;
        return $this;
    }

    /**
     * Get the group that this story belongs to
     *
     * Systems under test can grow to encompass hundreds, if not thousands
     * of user stories.  To make this manageable at scale, we break down
     * each user story like this:
     *
     * Name    : Starts as a free user with 10 USD in credit
     * Category: Billing User Stories
     * Group   : User States
     *
     * The 'name' is the summary text of the user story itself, which
     * should be no longer than a single sentence, please.
     *
     * The 'category' is the general group that the user story belongs to.
     * These are the top-level groups, such as 'Registration', 'Billing'
     * and so forth.
     *
     * The 'group' is the specific group _inside_ the category that the
     * user story belongs to.  The groups are specific to the category.
     *
     * @return array<string> the group that this story belongs to
     */
    public function getGroup()
    {
        return $this->group;
    }

    /**
     * return the story's group as a printable string
     *
     * @return string
     */
    public function getGroupAsString()
    {
        return implode(" > ", $this->group);
    }

    /**
     * Set the group that this story belongs to
     *
     * Systems under test can grow to encompass hundreds, if not thousands
     * of user stories.  To make this manageable at scale, we break down
     * each user story like this:
     *
     * Name    : Starts as a free user with 10 USD in credit
     * Category: Billing User Stories
     * Group   : User States
     *
     * The 'name' is the summary text of the user story itself, which
     * should be no longer than a single sentence, please.
     *
     * The 'category' is the general group that the user story belongs to.
     * These are the top-level groups, such as 'Registration', 'Billing'
     * and so forth.
     *
     * The 'group' is the specific group _inside_ the category that the
     * user story belongs to.  The groups are specific to the category.
     *
     * @param  array<string> $newGroup
     * @return Story  $this
     */
    public function setGroup($newGroup)
    {
        $this->group = $newGroup;
        return $this;
    }

    /**
     * Get the name of this story
     *
     * Systems under test can grow to encompass hundreds, if not thousands
     * of user stories.  To make this manageable at scale, we break down
     * each user story like this:
     *
     * Name    : Starts as a free user with 10 USD in credit
     * Category: Billing User Stories
     * Group   : User States
     *
     * The 'name' is the summary text of the user story itself, which
     * should be no longer than a single sentence, please.
     *
     * The 'category' is the general group that the user story belongs to.
     * These are the top-level groups, such as 'Registration', 'Billing'
     * and so forth.
     *
     * The 'group' is the specific group _inside_ the category that the
     * user story belongs to.  The groups are specific to the category.
     *
     * @return string the name of this story
     */
    public function getName()
    {
        return $this->name;
    }

    /**
     * Set the name of this story
     *
     * Systems under test can grow to encompass hundreds, if not thousands
     * of user stories.  To make this manageable at scale, we break down
     * each user story like this:
     *
     * Name    : Starts as a free user with 10 USD in credit
     * Category: Billing User Stories
     * Group   : User States
     *
     * The 'name' is the summary text of the user story itself, which
     * should be no longer than a single sentence, please.
     *
     * The 'category' is the general group that the user story belongs to.
     * These are the top-level groups, such as 'Registration', 'Billing'
     * and so forth.
     *
     * The 'group' is the specific group _inside_ the category that the
     * user story belongs to.  The groups are specific to the category.
     *
     * @param  string $newName the name of this story
     * @return Story  $this
     */
    public function setName($newName)
    {
        $this->name = $newName;
        return $this;
    }

    /**
     * Set the parameters for this story
     *
     * Parameters are a way of passing settings between Stories and
     * StoryTemplates.
     *
     * Order of precedence:
     *
     * 1) Story
     * 2) StoryTemplates (in 'basedOn()' order)
     *    (templates cannot override each other)
     *
     * @param array $defaults
     *        a list of the parameters for this story
     */
    public function setParams($defaults)
    {
        $this->params = $defaults;
        return $this;
    }

    /**
     * @return array
     */
    public function getParams()
    {
        // our return value
        $return = array();

        // populate it with the parameters from the templates
        foreach ($this->storyTemplates as $template) {
            // get any params from the template
            $params = $template->getParams();

            // any params already set have precedence
            foreach ($params as $key => $value) {
                // do we have a clash?
                if (!isset($return[$key])) {
                    $return[$key] = $value;
                }
            }
        }

        // now, merge in our own params
        //
        // our params always take precedence over the params set
        // in the template(s)
        $return = array_merge($this->params, $return);

        // all done
        return $return;
    }

    /**
     * @return void
     */
    public function determineStoryFilename()
    {
        $trace = debug_backtrace();
        $this->storyFilename = $trace[1]['file'];
    }

    /**
     * @return string
     */
    public function getStoryFilename()
    {
        return $this->storyFilename;
    }

    // ====================================================================
    //
    // Metadata for which states the story is valid for
    //
    // --------------------------------------------------------------------

    public function addValidRole($role)

The parameter $role is not used and could be removed.

    {
        throw new E4xx_DeprecatedFeature('user roles in stories have been removed from Storyplayer v2.');
    }

    /**
     * Synonym for addValidRole()
     *
     * @see Story::addValidRole
     */
    public function andValidRole($role)

The parameter $role is not used and could be removed.

    {
        throw new E4xx_DeprecatedFeature('user roles in stories have been removed from Storyplayer v2.');
    }

    public function hasRole($roleName)

The parameter $roleName is not used and could be removed.

    {
        throw new E4xx_DeprecatedFeature('user roles in stories have been removed from Storyplayer v2.');
    }

    // ====================================================================
    //
    // Support for changing roles after a test has succeeded
    //
    // --------------------------------------------------------------------

    /**
     * get the role changes callback
     */
    public function getRoleChanges()
    {
        throw new E4xx_DeprecatedFeature('user roles in stories have been removed from Storyplayer v2.');
    }

    /**
     * has the role changes callback been set?
     */
    public function hasRoleChanges()
    {
        throw new E4xx_DeprecatedFeature('user roles in stories have been removed from Storyplayer v2.');
    }

    public function setRoleChanges($newCallback)

The parameter $newCallback is not used and could be removed.

    {
        throw new E4xx_DeprecatedFeature('user roles in stories have been removed from Storyplayer v2.');
    }

    // ====================================================================
    //
    // Information about story templates
    //
    // --------------------------------------------------------------------

    /**
     * set up any templated methods from a predefined class
     *
     * @return Story
     */
    public function basedOn(StoryTemplate $tmpl)
    {
        // tell the template which story it is being used with
        $tmpl->setStory($this);

        $tmpl->hasTestCanRunCheck()         && $this->addTestCanRunCheck($tmpl->getTestCanRunCheck());
        $tmpl->hasTestSetup()               && $this->addTestSetup($tmpl->getTestSetup());
        $tmpl->hasTestTeardown()            && $this->addTestTeardown($tmpl->getTestTeardown());
        $tmpl->hasPerPhaseSetup()           && $this->addPerPhaseSetup($tmpl->getPerPhaseSetup());
        $tmpl->hasPerPhaseTeardown()        && $this->addPerPhaseTeardown($tmpl->getPerPhaseTeardown());
        $tmpl->hasDeviceSetup()             && $this->addDeviceSetup($tmpl->getDeviceSetup());
        $tmpl->hasDeviceTeardown()          && $this->addDeviceTeardown($tmpl->getDeviceTeardown());
        $tmpl->hasHints()                   && $this->addHints($tmpl->getHints());
        $tmpl->hasPreTestPrediction()       && $this->addPreTestPrediction($tmpl->getPreTestPrediction());
        $tmpl->hasPreTestInspection()       && $this->addPreTestInspection($tmpl->getPreTestInspection());
        $tmpl->hasAction()                  && $this->addAction($tmpl->getAction());
        $tmpl->hasPostTestInspection()      && $this->addPostTestInspection($tmpl->getPostTestInspection());

        // remember this template for future use
        $this->storyTemplates[] = $tmpl;

        // Return $this for a fluent interface
        return $this;
    }

    /**
     * get a list of the templates that this story is based on, in order
     * or precedence
     *
     * can be empty
     *
     * @return array<StoryTemplate>
     */
    public function getStoryTemplates()
    {
        return $this->storyTemplates;
    }

    // ==================================================================
    //
    // Information about dependencies
    //
    // ------------------------------------------------------------------

    /**
     * @return int
     */
    public function getRequiredStoryplayerVersion()
    {
        return $this->compatibleVersion;
    }

    /**
     * @return Story
     */
    public function requiresStoryplayerVersion($version)
    {
        $this->compatibleVersion = $version;
        return $this;
    }

    // ====================================================================
    //
    // Information about environments
    //
    // --------------------------------------------------------------------

    /**
     * @return Story
     */
    public function runsOn($envName)
    {
        $this->whitelistedEnvironments[$envName] = true;
        return $this;
    }

    /**
     * @return Story
     */
    public function andOn($envName)
    {
        $this->whitelistedEnvironments[$envName] = true;
        return $this;
    }

    /**
     * @return array
     */
    public function getWhitelistedEnvironments()
    {
        return $this->whitelistedEnvironments;
    }

    /**
     * @return void
     */
    public function requiresTestEnvironmentWithRoles($roles)
    {
        $this->requiredTestEnvRoles = $roles;
    }

    /**
     * @return array
     */
    public function getRequiredTestEnvironmentRoles()
    {
        return $this->requiredTestEnvRoles;
    }

    // ==================================================================
    //
    // Device support
    //
    // ------------------------------------------------------------------

    /**
     * does this story want to keep the web browser open between phases?
     *
     * @return boolean
     */
    public function getPersistDevice()
    {
        return $this->persistDevice;
    }

    /**
     * tell Storyplayer to keep the web browser open between test phases
     *
     * by default, we close the browser after every phase, to make sure
     * that the next phase always starts with a browser in a known state
     */
    public function setPersistDevice()
    {
        $this->persistDevice = true;
        return $this;
    }

    // ====================================================================
    //
    // Information about how check if the test should run at all
    //
    // --------------------------------------------------------------------

    /**
     * get the callback which allows the story to be skipped
     *
     * @return array
     */
    public function getTestCanRunCheck()
    {
        return $this->testCanRunCheckCallback;
    }

    /**
     * do we have a 'check story can run' callback?
     *
     * @return boolean true if the callback exists
     */
    public function hasTestCanRunCheck()
    {
        return count($this->testCanRunCheckCallback) > 0;
    }

    /**
     * @return void
     */
    public function addTestCanRunCheck($newCallback)
    {
        $this->testCanRunCheckCallback[] = $newCallback;
    }

    // ====================================================================
    //
    // Information about how to setup and teardown the test environment
    //
    // This is a feature from Storyplayer v1 that we've dropped in v2
    //
    // --------------------------------------------------------------------

    public function setTestEnvironmentSetup($newCallback)

The parameter $newCallback is not used and could be removed.

    {
        throw new E4xx_DeprecatedFeature('TestEnvironmentSetup phase was removed from Storyplayer v2.');
    }

    public function addTestEnvironmentSetup($newCallback)

The parameter $newCallback is not used and could be removed.

    {
        throw new E4xx_DeprecatedFeature('TestEnvironmentSetup phase was removed from Storyplayer v2.');
    }

    public function setTestEnvironmentTeardown($newCallback)

The parameter $newCallback is not used and could be removed.

    {
        throw new E4xx_DeprecatedFeature('TestEnvironmentSetup phase was removed from Storyplayer v2.');
    }

    public function addTestEnvironmentTeardown($newCallback)

The parameter $newCallback is not used and could be removed.

    {
        throw new E4xx_DeprecatedFeature('TestEnvironmentSetup phase was removed from Storyplayer v2.');
    }

    // ====================================================================
    //
    // Information about how to setup and teardown the test
    //
    // --------------------------------------------------------------------

    /**
     * get the callback for per-story setup work
     *
     * @return array
     */
    public function getTestSetup()
    {
        return $this->testSetupCallback;
    }

    /**
     * do we have a pre-story setup callback?
     *
     * @return boolean true if there is a pre-story setup callback
     */
    public function hasTestSetup()
    {
        return count($this->testSetupCallback) > 0;
    }

    public function addTestSetup($newCallback)
    {
        $this->testSetupCallback[] = $newCallback;
    }

    /**
     * get the callback for post-story teardown work
     *
     * @return array
     */
    public function getTestTeardown()
    {
        return $this->testTeardownCallback;
    }

    /**
     * do we have a post-story teardown callback?
     *
     * @return boolean true if there is a post-story teardown callback
     */
    public function hasTestTeardown()
    {
        return count($this->testTeardownCallback) > 0;
    }

    /**
     * @return void
     */
    public function addTestTeardown($newCallback)
    {
        $this->testTeardownCallback[] = $newCallback;
    }

    // ====================================================================
    //
    // Actions to happen before and after every phase of the test
    //
    // --------------------------------------------------------------------

    /**
     * get the callback for per-phase setup work
     *
     * @return array
     */
    public function getPerPhaseSetup()
    {
        return $this->perPhaseSetupCallback;
    }

    /**
     * do we have a per-phase setup callback?
     *
     * @return boolean true if there is a per-phase setup callback
     */
    public function hasPerPhaseSetup()
    {
        return count($this->perPhaseSetupCallback) > 0;
    }

    /**
     * @return void
     */
    public function addPerPhaseSetup($newCallback)
    {
        $this->perPhaseSetupCallback[] = $newCallback;
    }

    /**
     * get the callback for per-phase teardown work
     *
     * @return array
     */
    public function getPerPhaseTeardown()
    {
        return $this->perPhaseTeardownCallback;
    }

    /**
     * do we have a per-phase teardown callback?
     *
     * @return boolean true if there is a per-phase teardown callback
     */
    public function hasPerPhaseTeardown()
    {
        return count($this->perPhaseTeardownCallback) > 0;
    }

    /**
     * @return void
     */
    public function addPerPhaseTeardown($newCallback)
    {
        $this->perPhaseTeardownCallback[] = $newCallback;
    }

    // ====================================================================
    //
    // Actions to happen when starting and stopping test devices
    //
    // --------------------------------------------------------------------

    /**
     * get the callback for device setup work
     *
     * @return array
     */
    public function getDeviceSetup()
    {
        return $this->deviceSetupCallback;
    }

    /**
     * do we have a device setup callback?
     *
     * @return boolean true if there is a device setup callback
     */
    public function hasDeviceSetup()
    {
        return count($this->deviceSetupCallback) > 0;
    }

    /**
     * @return void
     */
    public function addDeviceSetup($newCallback)
    {
        $this->deviceSetupCallback[] = $newCallback;
    }

    /**
     * get the callback for device teardown work
     *
     * @return array
     */
    public function getDeviceTeardown()
    {
        return $this->deviceTeardownCallback;
    }

    /**
     * do we have a device teardown callback?
     *
     * @return boolean true if there is a device teardown callback
     */
    public function hasDeviceTeardown()
    {
        return count($this->deviceTeardownCallback) > 0;
    }

    /**
     * @return void
     */
    public function addDeviceTeardown($newCallback)
    {
        $this->deviceTeardownCallback[] = $newCallback;
    }

    // ====================================================================
    //
    // Information about how the story changes the system
    //
    // --------------------------------------------------------------------

    /**
     * get the hints callback
     *
     * @return callable
     */
    public function getHints()
    {
        return $this->hintsCallback;
    }

    /**
     * have any hints been set?
     *
     * @return boolean true if the callback has been set
     */
    public function hasHints()
    {
        return count($this->hintsCallback) > 0;
    }

    /**
     * @return void
     */
    public function setHints($newCallback)
    {
        $this->hintsCallback = array($newCallback);
    }

    /**
     * @return void
     */
    public function addHints($newCallback)
    {
        $this->hintsCallback[] = $newCallback;
    }

    // ====================================================================
    //
    // Before and after tests
    //
    // --------------------------------------------------------------------

    /**
     * get the callback to use to perform the preflight checks
     *
     * @return array
     */
    public function getPreTestPrediction()
    {
        return $this->preTestPredictionCallback;
    }

    /**
     * do we have a callback
     * @return boolean [description]
     */
    public function hasPreTestPrediction()
    {
        return count($this->preTestPredictionCallback) > 0;
    }

    /**
     * @return void
     */
    public function addPreTestPrediction($newCallback)
    {
        $this->preTestPredictionCallback[] = $newCallback;
    }

    // ====================================================================
    //
    // Checkpoint the relevant system state before actions occur
    //
    // --------------------------------------------------------------------

    /**
     * get the callback to use to perform the preflight checkpoint
     *
     * @return array
     */
    public function getPreTestInspection()
    {
        return $this->preTestInspectionCallback;
    }

    /**
     * do we have a callback
     * @return boolean [description]
     */
    public function hasPreTestInspection()
    {
        return count($this->preTestInspectionCallback) > 0;
    }

    /**
     * @return void
     */
    public function addPreTestInspection($newCallback)
    {
        $this->preTestInspectionCallback[] = $newCallback;
    }

    // ====================================================================
    //
    // Add in the actions that make the story come to life
    //
    // --------------------------------------------------------------------

    /**
     * @return void
     */
    public function addAction($newCallback)
    {
        $this->actionsCallbacks[] = $newCallback;
    }

    /**
     * @return void
     */
    public function addActions($newCallback)
    {
        $this->actionsCallbacks[] = $newCallback;
    }

    /**
     * pick one action at random, and return it to the caller
     *
     * @return callable
     */
    public function getOneAction()
    {
        // do we have any callbacks to pick from?
        if (count($this->actionsCallbacks) == 0)
        {
            throw new E5xx_NoStoryActions($this->getName());
        }

        // pick one story
        $i = rand(0, count($this->actionsCallbacks) - 1);

        // return it to the caller
        return $this->actionsCallbacks[$i];
    }

    /**
     * does this story have any actions?
     *
     * @return boolean true if this story has any actions
     */
    public function hasActions()
    {
        return (count($this->actionsCallbacks) > 0);
    }

    // ====================================================================
    //
    // Determine whether the test passed or failed
    //
    // --------------------------------------------------------------------

    /**
     * get the callback to use to work out the test results
     *
     * @return array
     */
    public function getPostTestInspection()
    {
        return $this->postTestInspectionCallback;
    }

    /**
     * @return bool
     */
    public function hasPostTestInspection()
    {
        return count($this->postTestInspectionCallback) > 0;
    }

    /**
     * @return void
     */
    public function addPostTestInspection($newCallback)
    {
        $this->postTestInspectionCallback[] = $newCallback;
    }

    // ====================================================================
    //
    // Our default behaviour when the story object is instantiated
    //
    // --------------------------------------------------------------------

    /**
     * @return void
     */
    public function setDefaultCallbacks()
    {
        // 1: test setup
        if (!$this->hasTestSetup()) {
            $this->addTestSetup(function(StoryTeller $st) {
                $st->usingReporting()->reportNotRequired();
            });
        }

        // 2: pre-test prediction
        if (!$this->hasPreTestPrediction()) {
            $this->addPreTestPrediction(function(StoryTeller $st) {
                $st->usingReporting()->reportShouldAlwaysSucceed();
            });
        }

        // 3: pre-test inspection
        if (!$this->hasPreTestInspection()) {
            $this->addPreTestInspection(function(StoryTeller $st) {
                $st->usingReporting()->reportNotRequired();
            });
        }

        // 4: test action
        //
        // we set no default for this, because we do not want the action
        // to be chosen by StoryPlayer
        //
        // (StoryPlayer chooses one action at random from the set of
        // supplied actions)

        // 5: post-test inspection
        //
        // we set no default for this, because each story must provide
        // this

        // 6: test tear down
        if (!$this->hasTestTeardown()) {
            $this->addTestTeardown(function(StoryTeller $st) {
                $st->usingReporting()->reportNotRequired();
            });
        }

        // all done
    }

    // ====================================================================
    //
    // Serialisation and other format convertors
    //
    // --------------------------------------------------------------------

    /**
     * return a string representation of the story, for things like logging
     * @return string
     */
    public function __toString()
    {
        return $this->getCategory() . ' :: ' . $this->getGroupAsString() . ' :: ' . $this->getName();
    }

    // ==================================================================
    //
    // Dealing with the story result
    //
    // ------------------------------------------------------------------

    /**
     * @return Story_Result
     */
    public function getResult()
    {
        if (!isset($this->storyResult)) {
            $this->storyResult = new Story_Result($this);
        }

        return $this->storyResult;
    }
}