class FunctionalTest extends SapphireTest implements TestOnly

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.")); }

Methods

static TempDatabase
tempDB()

No description

static array
getIllegalExtensions()

Gets illegal extensions for this class

static array
getRequiredExtensions()

Gets required extensions for this class

static String
get_fixture_file()

No description

bool
getUsesDatabase()

No description

bool
getUsesTransactions()

No description

array
getRequireDefaultRecordsFrom()

No description

static 
setUpBeforeClass()

Called once per test case ({@link SapphireTest} subclass).

static 
tearDownAfterClass()

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

getFixtureFactory() deprecated

No description

$this
setFixtureFactory(FixtureFactory $factory) deprecated

Sets a new fixture factory

loadFixture(string $fixtureFile) deprecated

Load a YAML fixture file into the database.

clearFixtures()

Clear all fixtures which were previously loaded through {@link loadFixture()}

static 
assertContains($needle, $haystack, $message = '', $ignoreCase = false, $checkForObjectIdentity = true, $checkForNonObjectIdentity = false)

No description

static 
assertNotContains($needle, $haystack, $message = '', $ignoreCase = false, $checkForObjectIdentity = true, $checkForNonObjectIdentity = false)

No description

bool
clearEmails()

Clear the log of emails sent

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

Search for an email that was sent.

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.

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

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

assertDOSContains($matches, $dataObjectSet) deprecated

No description

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

static 
assertNotDOSContains($matches, $dataObjectSet) deprecated

No description

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

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

assertDOSEquals($matches, SS_List $dataObjectSet) deprecated

No description

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

Assert that the every record in the given {@link SS_List} matches the given key-value pairs.

assertDOSAllMatch($match, SS_List $dataObjectSet) deprecated

No description

static 
assertSQLEquals(string $expectedSQL, string $actualSQL, string $message = '', float|int $delta, integer $maxDepth = 10, boolean $canonicalize = false, boolean $ignoreCase = false)

Asserts that two SQL queries are equivalent

static 
assertSQLContains(string $needleSQL, string $haystackSQL, string $message = '', boolean $ignoreCase = false, boolean $checkForObjectIdentity = true)

Asserts that a SQL query contains a SQL fragment

static 
assertSQLNotContains(string $needleSQL, string $haystackSQL, string $message = '', boolean $ignoreCase = false, boolean $checkForObjectIdentity = true)

Asserts that a SQL query contains a SQL fragment

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

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

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

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

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

logInAs(Member|int|string $member)

Log in as the given member

logOut()

Log out the current user

static array
getExtraDataObjects()

Return all extra objects to scaffold for this test

static array
getExtraControllers()

Get additional controller classes to register routes for

session()

Returns the {@link Session} object for this test

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

Submit a get request

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

Submit a post request

submitForm(string $formID, string $button = null, array $data = array())

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

string
content()

Return the most recent content

findAttribute(SimpleXMLElement $object, string $attribute)

Find an attribute in a SimpleXMLElement object by name.

cssParser()

Return a CSSContentParser for the most recent content.

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.

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.

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.

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.

useDraftSite(bool $enabled = true) deprecated

Use the draft (stage) site for testing.

static bool
get_disable_themes()

No description

static bool
get_use_draft_site() deprecated

No description

Details

in SapphireTest at line 174
static TempDatabase tempDB()

Return Value

TempDatabase

in SapphireTest at line 187
static array getIllegalExtensions()

Gets illegal extensions for this class

Return Value

array

in SapphireTest at line 197
static array getRequiredExtensions()

Gets required extensions for this class

Return Value

array

in SapphireTest at line 226
static String get_fixture_file()

Return Value

String

in SapphireTest at line 234
bool getUsesDatabase()

Return Value

bool

in SapphireTest at line 242
bool getUsesTransactions()

Return Value

bool

in SapphireTest at line 250
array getRequireDefaultRecordsFrom()

Return Value

array

in SapphireTest at line 382
static setUpBeforeClass()

Called once per test case ({@link SapphireTest} subclass).

This is different to {@link 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 {@link 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

Exceptions

Exception

in SapphireTest at line 411
static 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

in SapphireTest at line 424
FixtureFactory|false getFixtureFactory() deprecated

deprecated 4.0.0:5.0.0

Return Value

FixtureFactory|false

in SapphireTest at line 438
$this setFixtureFactory(FixtureFactory $factory) deprecated

deprecated 4.0.0:5.0.0

Sets a new fixture factory

Parameters

FixtureFactory $factory

Return Value

$this

in SapphireTest at line 519
loadFixture(string $fixtureFile) deprecated

deprecated 4.0.0:5.0.0

Load a YAML fixture file into the database.

Once loaded, you can use idFromFixture() and objFromFixture() to get items from the fixture. Doesn't clear existing fixtures.

Parameters

string $fixtureFile The location of the .yml fixture file, relative to the site base dir

in SapphireTest at line 530
clearFixtures()

Clear all fixtures which were previously loaded through {@link loadFixture()}

in SapphireTest at line 592
static assertContains($needle, $haystack, $message = '', $ignoreCase = false, $checkForObjectIdentity = true, $checkForNonObjectIdentity = false)

Parameters

$needle
$haystack
$message
$ignoreCase
$checkForObjectIdentity
$checkForNonObjectIdentity

in SapphireTest at line 606
static assertNotContains($needle, $haystack, $message = '', $ignoreCase = false, $checkForObjectIdentity = true, $checkForNonObjectIdentity = false)

Parameters

$needle
$haystack
$message
$ignoreCase
$checkForObjectIdentity
$checkForNonObjectIdentity

in SapphireTest at line 625
bool clearEmails()

Clear the log of emails sent

Return Value

bool True if emails cleared

in SapphireTest at line 646
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'

in SapphireTest at line 665
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

in SapphireTest at line 715
static assertListContains(SS_List|array $matches, SS_List $list, string $message = '')

Assert that the given {@link 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 {@link 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);

in SapphireTest at line 739
assertDOSContains($matches, $dataObjectSet) deprecated

deprecated 4.0.0:5.0.0 Use assertListContains() instead

Parameters

$matches
$dataObjectSet

in SapphireTest at line 765
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 {@link 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);

in SapphireTest at line 793
static assertNotDOSContains($matches, $dataObjectSet) deprecated

deprecated 4.0.0:5.0.0 Use assertListNotContains() instead

Parameters

$matches
$dataObjectSet

in SapphireTest at line 817
static assertListEquals(mixed $matches, SS_List $list, string $message = '')

Assert that the given {@link 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 {@link SS_List} to test.
string $message

in SapphireTest at line 841
assertDOSEquals($matches, SS_List $dataObjectSet) deprecated

deprecated 4.0.0:5.0.0 Use assertListEquals() instead

Parameters

$matches
SS_List $dataObjectSet

in SapphireTest at line 861
static assertListAllMatch(mixed $match, SS_List $list, string $message = '')

Assert that the every record in the given {@link 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 {@link SS_List} to test.
string $message

in SapphireTest at line 885
assertDOSAllMatch($match, SS_List $dataObjectSet) deprecated

deprecated 4.0.0:5.0.0 Use assertListAllMatch() instead

Parameters

$match
SS_List $dataObjectSet

in SapphireTest at line 914
static assertSQLEquals(string $expectedSQL, string $actualSQL, string $message = '', float|int $delta, integer $maxDepth = 10, boolean $canonicalize = false, boolean $ignoreCase = false)

Asserts that two SQL queries are equivalent

Parameters

string $expectedSQL
string $actualSQL
string $message
float|int $delta
integer $maxDepth
boolean $canonicalize
boolean $ignoreCase

in SapphireTest at line 939
static assertSQLContains(string $needleSQL, string $haystackSQL, string $message = '', boolean $ignoreCase = false, boolean $checkForObjectIdentity = true)

Asserts that a SQL query contains a SQL fragment

Parameters

string $needleSQL
string $haystackSQL
string $message
boolean $ignoreCase
boolean $checkForObjectIdentity

in SapphireTest at line 961
static assertSQLNotContains(string $needleSQL, string $haystackSQL, string $message = '', boolean $ignoreCase = false, boolean $checkForObjectIdentity = true)

Asserts that a SQL query contains a SQL fragment

Parameters

string $needleSQL
string $haystackSQL
string $message
boolean $ignoreCase
boolean $checkForObjectIdentity

in SapphireTest at line 977
static start()

Start test environment

in SapphireTest at line 1025
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

in SapphireTest at line 1045
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

in SapphireTest at line 1107
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

in SapphireTest at line 1119
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

in SapphireTest at line 1132
logOut()

Log out the current user

in SapphireTest at line 1191
static array getExtraDataObjects()

Return all extra objects to scaffold for this test

Return Value

array

in SapphireTest at line 1201
static array getExtraControllers()

Get additional controller classes to register routes for

Return Value

array

at line 79
Session session()

Returns the {@link Session} object for this test

Return Value

Session

at line 159
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

at line 181
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

at line 210
HTTPResponse submitForm(string $formID, string $button = null, array $data = array())

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.

Return Value

HTTPResponse

See also

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

at line 225
string content()

Return the most recent content

Return Value

string

at line 236
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

at line 252
CSSContentParser cssParser()

Return a CSSContentParser for the most recent content.

Return Value

CSSContentParser

at line 272
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

PHPUnit_Framework_AssertionFailedError

at line 309
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

PHPUnit_Framework_AssertionFailedError

at line 344
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

PHPUnit_Framework_AssertionFailedError

at line 382
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

PHPUnit_Framework_AssertionFailedError

at line 410
useDraftSite(bool $enabled = true) deprecated

deprecated 4.2.0:5.0.0 Use ?stage=Stage querystring arguments instead of useDraftSite

Use the draft (stage) site for testing.

This is helpful if you're not testing publication functionality and don't want "stage management" cluttering your test.

Parameters

bool $enabled toggle the use of the draft site

at line 425
static bool get_disable_themes()

Return Value

bool

at line 434
static bool get_use_draft_site() deprecated

deprecated 4.2.0:5.0.0 Use ?stage=Stage in your querystring arguments instead

Return Value

bool