abstract class FunctionalTest extends SapphireTest implements TestOnly (View source)

SilverStripe-specific testing object designed to support functional testing of your web app. It simulates get/post requests, form submission, and can validate resulting HTML, looking up content by CSS selector.

The example below shows how it works.

  public function testMyForm() {
  // Visit a URL
  $this->get("your/url");

  // Submit a form on the page that you get in response
  $this->submitForm("MyForm_ID", "action_dologin", array("Email" => "invalid email ^&*&^"));

  // Validate the content that is returned
  $this->assertExactMatchBySelector("#MyForm_ID p.error", array("That email address is invalid."));
 }

Properties

protected static string|array $fixture_file

Path to fixture data for this test run.

from  SapphireTest
protected bool $usesDatabase from  SapphireTest
protected bool $usesTransactions

This test will cleanup its state via transactions.

from  SapphireTest
protected static bool $is_running_test from  SapphireTest
protected array $requireDefaultRecordsFrom

By default, setUp() does not require default records. Pass class names in here, and the require/augment default records function will be called on them.

from  SapphireTest
protected static array $illegal_extensions

A list of extensions that can't be applied during the execution of this run. If they are applied, they will be temporarily removed and a database migration called.

from  SapphireTest
protected static array $required_extensions

A list of extensions that must be applied during the execution of this run. If they are not applied, they will be temporarily added and a database migration called.

from  SapphireTest
protected static array $extra_dataobjects

By default, the test database won't contain any DataObjects that have the interface TestOnly.

from  SapphireTest
protected static array $extra_controllers

List of class names of {Controller} objects to register routes for Controllers must implement Link() method

from  SapphireTest
protected $backupGlobals

We need to disabling backing up of globals to avoid overriding the few globals SilverStripe relies on, like $lang for the i18n subsystem.

from  SapphireTest
protected static SapphireTestState $state

State management container for SapphireTest

from  SapphireTest
protected static TempDatabase $tempDB

Temp database helper

from  SapphireTest
protected FixtureFactory|bool $fixtureFactory from  SapphireTest
protected $cache_generatedMembers

Cache for logInWithPermission()

from  SapphireTest
protected static bool $disable_themes

Set this to true on your sub-class to disable the use of themes in this test.

protected TestSession $mainSession
protected CSSContentParser $cssParser

CSSContentParser for the most recently requested page.

protected bool $autoFollowRedirection

If this is true, then 30x Location headers will be automatically followed.

Methods

public static 
tempDB()

No description

public static 
array
getIllegalExtensions()

Gets illegal extensions for this class

public static 
array
getRequiredExtensions()

Gets required extensions for this class

protected static 
bool
is_running_test()

Check if test bootstrapping has been performed. Must not be relied on outside of unit tests.

protected static 
set_is_running_test(bool $bool)

Set test running state

public static 
string
get_fixture_file()

No description

public
bool
getUsesDatabase()

No description

public
bool
getUsesTransactions()

No description

public
array
getRequireDefaultRecordsFrom()

No description

public
void
onBeforeLoadFixtures()

Called after the database is created, but before fixtures are loaded.

protected
void
setUp()

Setup the test.

protected
bool
shouldSetupDatabaseForCurrentTest($fixtureFiles)

Helper method to determine if the current test should enable a test database

protected
bool
currentTestEnablesDatabase()

Helper method to check, if the current test uses the database.

protected
bool
currentTestDisablesDatabase()

Helper method to check, if the current test uses the database.

public static 
void
setUpBeforeClass()

Called once per test case (SapphireTest subclass).

public static 
void
tearDownAfterClass()

tearDown method that's called once per test class rather once per test method.

protected
int
idFromFixture(string $className, string $identifier)

Get the ID of an object from the fixture.

protected
array
allFixtureIDs(string $className)

Return all of the IDs in the fixture of a particular class name.

protected
T
objFromFixture(T> $className, string $identifier)

Get an object from the fixture.

public
clearFixtures()

Clear all fixtures which were previously loaded through loadFixture()

protected
string
getCurrentAbsolutePath()

Useful for writing unit tests without hardcoding folder structures.

protected
string
getCurrentRelativePath()

No description

protected
void
tearDown()

Setup the test.

public
bool
clearEmails()

Clear the log of emails sent

public static 
array|null
findEmail(string $to, string $from = null, string $subject = null, string $content = null)

Search for an email that was sent.

public static 
assertEmailSent(string $to, string $from = null, string $subject = null, string $content = null)

Assert that the matching email was sent since the last call to clearEmails() All of the parameters can either be a string, or, if they start with "/", a PREG-compatible regular expression.

public static 
assertListContains(SS_List|array $matches, SS_List $list, string $message = '')

Assert that the given SS_List includes DataObjects matching the given key-value pairs. Each match must correspond to 1 distinct record.

public static 
assertListNotContains(SS_List|array $matches, SS_List $list, string $message = '')

Asserts that no items in a given list appear in the given dataobject list

public static 
assertListEquals(mixed $matches, SS_List $list, string $message = '')

Assert that the given SS_List includes only DataObjects matching the given key-value pairs. Each match must correspond to 1 distinct record.

public static 
assertListAllMatch(mixed $match, SS_List $list, string $message = '')

Assert that the every record in the given SS_List matches the given key-value pairs.

protected static 
string
normaliseSQL(string $sql)

Removes sequences of repeated whitespace characters from SQL queries making them suitable for string comparison

public static 
assertSQLEquals(string $expectedSQL, string $actualSQL, string $message = '')

Asserts that two SQL queries are equivalent

public static 
assertSQLContains(string $needleSQL, string $haystackSQL, string $message = '')

Asserts that a SQL query contains a SQL fragment

public static 
assertSQLNotContains(string $needleSQL, string $haystackSQL, string $message = '')

Asserts that a SQL query contains a SQL fragment

public static 
start()

Start test environment

public static 
resetDBSchema(bool $includeExtraDataObjects = false, bool $forceCreate = false)

Reset the testing database's schema, but only if it is active

public
mixed
actWithPermission(string|array $permCode, callable $callback)

A wrapper for automatically performing callbacks as a user with a specific permission

protected
createMemberWithPermission(string|array $permCode)

Create Member and Group objects on demand with specific permission code

public
int
logInWithPermission(string|array $permCode = 'ADMIN')

Create a member and group with the given permission code, and log in with it.

public
logInAs(Member|int|string $member)

Log in as the given member

public
logOut()

Log out the current user

protected
useTestTheme(string $themeBaseDir, string $theme, callable $callback)

Test against a theme.

protected
array
getFixturePaths()

Get fixture paths for this test

public static 
array
getExtraDataObjects()

Return all extra objects to scaffold for this test

public static 
array
getExtraControllers()

Get additional controller classes to register routes for

protected
string
resolveFixturePath(string $fixtureFilePath)

Map a fixture path to a physical file

protected
setUpRoutes()

No description

protected
array
getExtraRoutes()

Get extra routes to merge into Director.rules

public static 
createInvalidArgumentException($argument, $type, $value = null)

Reimplementation of phpunit5 PHPUnit_Util_InvalidArgumentHelper::factory()

public
array
getAnnotations()

Returns the annotations for this test.

protected
mockSleep(int $seconds)

Test safe version of sleep()

public
session()

Returns the Session object for this test

protected
withBaseURL(string $url, callable $callback)

Run a test while mocking the base url with the provided value

protected
withBaseFolder(string $folder, callable $callback)

Run a test while mocking the base folder with the provided value

public
get(string $url, Session $session = null, array $headers = null, array $cookies = null)

Submit a get request

public
post(string $url, array $data, array $headers = null, Session $session = null, string $body = null, array $cookies = null)

Submit a post request

public
submitForm(string $formID, string $button = null, array $data = [], bool $withSecurityToken = true)

Submit the form with the given HTML ID, filling it out with the given data.

public
string
content()

Return the most recent content

public
findAttribute(SimpleXMLElement $object, string $attribute)

Find an attribute in a SimpleXMLElement object by name.

public
cssParser()

Return a CSSContentParser for the most recent content.

public
assertPartialMatchBySelector(string $selector, array|string $expectedMatches, string $message = null)

Assert that the most recently queried page contains a number of content tags specified by a CSS selector.

public
assertExactMatchBySelector(string $selector, array|string $expectedMatches, string $message = null)

Assert that the most recently queried page contains a number of content tags specified by a CSS selector.

public
assertPartialHTMLMatchBySelector(string $selector, array|string $expectedMatches, string $message = null)

Assert that the most recently queried page contains a number of content tags specified by a CSS selector.

public
assertExactHTMLMatchBySelector(string $selector, array|string $expectedMatches, string $message = null)

Assert that the most recently queried page contains a number of content tags specified by a CSS selector.

public static 
bool
get_disable_themes()

No description

Details

static TempDatabase tempDB()

No description

Return Value

TempDatabase

static array getIllegalExtensions()

Gets illegal extensions for this class

Return Value

array

static array getRequiredExtensions()

Gets required extensions for this class

Return Value

array

static protected bool is_running_test()

Check if test bootstrapping has been performed. Must not be relied on outside of unit tests.

Return Value

bool

static protected set_is_running_test(bool $bool)

Set test running state

Parameters

bool $bool

static string get_fixture_file()

No description

Return Value

string

bool getUsesDatabase()

No description

Return Value

bool

bool getUsesTransactions()

No description

Return Value

bool

array getRequireDefaultRecordsFrom()

No description

Return Value

array

void onBeforeLoadFixtures()

Called after the database is created, but before fixtures are loaded.

Return Value

void

protected void setUp()

Setup the test.

Always sets up in order:

  • Reset php state
  • Nest
  • Custom state helpers

User code should call parent::setUp() before custom setup code

Return Value

void

protected bool shouldSetupDatabaseForCurrentTest($fixtureFiles)

Helper method to determine if the current test should enable a test database

Parameters

$fixtureFiles

Return Value

bool

protected bool currentTestEnablesDatabase()

Helper method to check, if the current test uses the database.

This can be switched on with the annotation "@useDatabase"

Return Value

bool

protected bool currentTestDisablesDatabase()

Helper method to check, if the current test uses the database.

This can be switched on with the annotation "@useDatabase false"

Return Value

bool

static void setUpBeforeClass()

Called once per test case (SapphireTest subclass).

This is different to setUp(), which gets called once per method. Useful to initialize expensive operations which don't change state for any called method inside the test, e.g. dynamically adding an extension. See teardownAfterClass() for tearing down the state again.

Always sets up in order:

  • Reset php state
  • Nest
  • Custom state helpers

User code should call parent::setUpBeforeClass() before custom setup code

Return Value

void

Exceptions

Exception

static void tearDownAfterClass()

tearDown method that's called once per test class rather once per test method.

Always sets up in order:

  • Custom state helpers
  • Unnest
  • Reset php state

User code should call parent::tearDownAfterClass() after custom tear down code

Return Value

void

protected int idFromFixture(string $className, string $identifier)

Get the ID of an object from the fixture.

Parameters

string $className

The data class or table name, as specified in your fixture file. Parent classes won't work

string $identifier

The identifier string, as provided in your fixture file

Return Value

int

protected array allFixtureIDs(string $className)

Return all of the IDs in the fixture of a particular class name.

Will collate all IDs form all fixtures if multiple fixtures are provided.

Parameters

string $className

The data class or table name, as specified in your fixture file

Return Value

array

A map of fixture-identifier => object-id

protected T objFromFixture(T> $className, string $identifier)

Get an object from the fixture.

Parameters

T> $className

The data class or table name, as specified in your fixture file. Parent classes won't work

string $identifier

The identifier string, as provided in your fixture file

Return Value

T

clearFixtures()

Clear all fixtures which were previously loaded through loadFixture()

protected string getCurrentAbsolutePath()

Useful for writing unit tests without hardcoding folder structures.

Return Value

string

Absolute path to current class.

protected string getCurrentRelativePath()

No description

Return Value

string

File path relative to webroot

protected void tearDown()

Setup the test.

Always sets up in order:

  • Custom state helpers
  • Unnest
  • Reset php state

User code should call parent::tearDown() after custom tear down code

Return Value

void

bool clearEmails()

Clear the log of emails sent

Return Value

bool

True if emails cleared

static array|null findEmail(string $to, string $from = null, string $subject = null, string $content = null)

Search for an email that was sent.

All of the parameters can either be a string, or, if they start with "/", a PREG-compatible regular expression.

Parameters

string $to
string $from
string $subject
string $content

Return Value

array|null

Contains keys: 'Type', 'To', 'From', 'Subject', 'Content', 'PlainContent', 'AttachedFiles', 'HtmlContent'

static assertEmailSent(string $to, string $from = null, string $subject = null, string $content = null)

Assert that the matching email was sent since the last call to clearEmails() All of the parameters can either be a string, or, if they start with "/", a PREG-compatible regular expression.

Parameters

string $to
string $from
string $subject
string $content

static assertListContains(SS_List|array $matches, SS_List $list, string $message = '')

Assert that the given SS_List includes DataObjects matching the given key-value pairs. Each match must correspond to 1 distinct record.

Parameters

SS_List|array $matches

The patterns to match. Each pattern is a map of key-value pairs. You can either pass a single pattern or an array of patterns.

SS_List $list

The SS_List to test.

string $message

Examples

Check that $members includes an entry with Email = [email protected]: $this->assertListContains(['Email' => '[email protected]'], $members);

Check that $members includes entries with Email = [email protected] and with Email = [email protected]: $this->assertListContains([ ['Email' => '[email protected]'], ['Email' => '[email protected]'], ], $members);

static assertListNotContains(SS_List|array $matches, SS_List $list, string $message = '')

Asserts that no items in a given list appear in the given dataobject list

Parameters

SS_List|array $matches

The patterns to match. Each pattern is a map of key-value pairs. You can either pass a single pattern or an array of patterns.

SS_List $list

The SS_List to test.

string $message

Examples

Check that $members doesn't have an entry with Email = [email protected]: $this->assertListNotContains(['Email' => '[email protected]'], $members);

Check that $members doesn't have entries with Email = [email protected] and with Email = [email protected]: $this->assertListNotContains([ ['Email' => '[email protected]'], ['Email' => '[email protected]'], ], $members);

static assertListEquals(mixed $matches, SS_List $list, string $message = '')

Assert that the given SS_List includes only DataObjects matching the given key-value pairs. Each match must correspond to 1 distinct record.

Example

Check that only the entries Sam Minnee and Ingo Schommer exist in $members. Order doesn't matter: $this->assertListEquals([ ['FirstName' =>'Sam', 'Surname' => 'Minnee'], ['FirstName' => 'Ingo', 'Surname' => 'Schommer'], ], $members);

Parameters

mixed $matches

The patterns to match. Each pattern is a map of key-value pairs. You can either pass a single pattern or an array of patterns.

SS_List $list

The SS_List to test.

string $message

static assertListAllMatch(mixed $match, SS_List $list, string $message = '')

Assert that the every record in the given SS_List matches the given key-value pairs.

Example

Check that every entry in $members has a Status of 'Active': $this->assertListAllMatch(['Status' => 'Active'], $members);

Parameters

mixed $match

The pattern to match. The pattern is a map of key-value pairs.

SS_List $list

The SS_List to test.

string $message

static protected string normaliseSQL(string $sql)

Removes sequences of repeated whitespace characters from SQL queries making them suitable for string comparison

Parameters

string $sql

Return Value

string

The cleaned and normalised SQL string

static assertSQLEquals(string $expectedSQL, string $actualSQL, string $message = '')

Asserts that two SQL queries are equivalent

Parameters

string $expectedSQL
string $actualSQL
string $message

static assertSQLContains(string $needleSQL, string $haystackSQL, string $message = '')

Asserts that a SQL query contains a SQL fragment

Parameters

string $needleSQL
string $haystackSQL
string $message

static assertSQLNotContains(string $needleSQL, string $haystackSQL, string $message = '')

Asserts that a SQL query contains a SQL fragment

Parameters

string $needleSQL
string $haystackSQL
string $message

static start()

Start test environment

static resetDBSchema(bool $includeExtraDataObjects = false, bool $forceCreate = false)

Reset the testing database's schema, but only if it is active

Parameters

bool $includeExtraDataObjects

If true, the extraDataObjects tables will also be included

bool $forceCreate

Force DB to be created if it doesn't exist

mixed actWithPermission(string|array $permCode, callable $callback)

A wrapper for automatically performing callbacks as a user with a specific permission

Parameters

string|array $permCode
callable $callback

Return Value

mixed

protected Member createMemberWithPermission(string|array $permCode)

Create Member and Group objects on demand with specific permission code

Parameters

string|array $permCode

Return Value

Member

int logInWithPermission(string|array $permCode = 'ADMIN')

Create a member and group with the given permission code, and log in with it.

Returns the member ID.

Parameters

string|array $permCode

Either a permission, or list of permissions

Return Value

int

Member ID

logInAs(Member|int|string $member)

Log in as the given member

Parameters

Member|int|string $member

The ID, fixture codename, or Member object of the member that you want to log in

logOut()

Log out the current user

protected useTestTheme(string $themeBaseDir, string $theme, callable $callback)

Test against a theme.

Parameters

string $themeBaseDir

themes directory

string $theme

Theme name

callable $callback

Exceptions

Exception

protected array getFixturePaths()

Get fixture paths for this test

Return Value

array

List of paths

static array getExtraDataObjects()

Return all extra objects to scaffold for this test

Return Value

array

static array getExtraControllers()

Get additional controller classes to register routes for

Return Value

array

protected string resolveFixturePath(string $fixtureFilePath)

Map a fixture path to a physical file

Parameters

string $fixtureFilePath

Return Value

string

protected setUpRoutes()

No description

protected array getExtraRoutes()

Get extra routes to merge into Director.rules

Return Value

array

static createInvalidArgumentException($argument, $type, $value = null)

Reimplementation of phpunit5 PHPUnit_Util_InvalidArgumentHelper::factory()

Parameters

$argument
$type
$value

array getAnnotations()

Returns the annotations for this test.

Return Value

array

protected DBDatetime mockSleep(int $seconds)

Test safe version of sleep()

Parameters

int $seconds

Return Value

DBDatetime

Exceptions

Exception

Session session()

Returns the Session object for this test

Return Value

Session

protected withBaseURL(string $url, callable $callback)

Run a test while mocking the base url with the provided value

Parameters

string $url

The base URL to use for this test

callable $callback

The test to run

protected withBaseFolder(string $folder, callable $callback)

Run a test while mocking the base folder with the provided value

Parameters

string $folder

The base folder to use for this test

callable $callback

The test to run

HTTPResponse get(string $url, Session $session = null, array $headers = null, array $cookies = null)

Submit a get request

Parameters

string $url
Session $session
array $headers
array $cookies

Return Value

HTTPResponse

HTTPResponse post(string $url, array $data, array $headers = null, Session $session = null, string $body = null, array $cookies = null)

Submit a post request

Parameters

string $url
array $data
array $headers
Session $session
string $body
array $cookies

Return Value

HTTPResponse

HTTPResponse submitForm(string $formID, string $button = null, array $data = [], bool $withSecurityToken = true)

Submit the form with the given HTML ID, filling it out with the given data.

Acts on the most recent response.

Any data parameters have to be present in the form, with exact form field name and values, otherwise they are removed from the submission.

Caution: Parameter names have to be formatted as they are in the form submission, not as they are interpreted by PHP. Wrong: array('mycheckboxvalues' => array(1 => 'one', 2 => 'two')) Right: array('mycheckboxvalues[1]' => 'one', 'mycheckboxvalues[2]' => 'two')

Parameters

string $formID

HTML 'id' attribute of a form (loaded through a previous response)

string $button

HTML 'name' attribute of the button (NOT the 'id' attribute)

array $data

Map of GET/POST data.

bool $withSecurityToken

Submit with the form's security token if there is one.

Return Value

HTTPResponse

See also

http://www.simpletest.org/en/form_testing_documentation.html

string content()

Return the most recent content

Return Value

string

SimpleXMLElement findAttribute(SimpleXMLElement $object, string $attribute)

Find an attribute in a SimpleXMLElement object by name.

Parameters

SimpleXMLElement $object
string $attribute

Name of attribute to find

Return Value

SimpleXMLElement

object of the attribute

CSSContentParser cssParser()

Return a CSSContentParser for the most recent content.

Return Value

CSSContentParser

assertPartialMatchBySelector(string $selector, array|string $expectedMatches, string $message = null)

Assert that the most recently queried page contains a number of content tags specified by a CSS selector.

The given CSS selector will be applied to the HTML of the most recent page. The content of every matching tag will be examined. The assertion fails if one of the expectedMatches fails to appear.

Note:   characters are stripped from the content; make sure that your assertions take this into account.

Parameters

string $selector

A basic CSS selector, e.g. 'li.jobs h3'

array|string $expectedMatches

The content of at least one of the matched tags

string $message

Exceptions

AssertionFailedError

assertExactMatchBySelector(string $selector, array|string $expectedMatches, string $message = null)

Assert that the most recently queried page contains a number of content tags specified by a CSS selector.

The given CSS selector will be applied to the HTML of the most recent page. The full HTML of every matching tag will be examined. The assertion fails if one of the expectedMatches fails to appear.

Note:   characters are stripped from the content; make sure that your assertions take this into account.

Parameters

string $selector

A basic CSS selector, e.g. 'li.jobs h3'

array|string $expectedMatches

The content of all matching tags as an array

string $message

Exceptions

AssertionFailedError

assertPartialHTMLMatchBySelector(string $selector, array|string $expectedMatches, string $message = null)

Assert that the most recently queried page contains a number of content tags specified by a CSS selector.

The given CSS selector will be applied to the HTML of the most recent page. The content of every matching tag will be examined. The assertion fails if one of the expectedMatches fails to appear.

Note:   characters are stripped from the content; make sure that your assertions take this into account.

Parameters

string $selector

A basic CSS selector, e.g. 'li.jobs h3'

array|string $expectedMatches

The content of at least one of the matched tags

string $message

Exceptions

AssertionFailedError

assertExactHTMLMatchBySelector(string $selector, array|string $expectedMatches, string $message = null)

Assert that the most recently queried page contains a number of content tags specified by a CSS selector.

The given CSS selector will be applied to the HTML of the most recent page. The full HTML of every matching tag will be examined. The assertion fails if one of the expectedMatches fails to appear.

Note:   characters are stripped from the content; make sure that your assertions take this into account.

Parameters

string $selector

A basic CSS selector, e.g. 'li.jobs h3'

array|string $expectedMatches

The content of all matched tags as an array

string $message

Exceptions

AssertionFailedError

static bool get_disable_themes()

No description

Return Value

bool