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

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 = 0, int $maxDepth = 10, bool $canonicalize = false, bool $ignoreCase = false)

Asserts that two SQL queries are equivalent

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

Asserts that a SQL query contains a SQL fragment

static 
assertSQLNotContains(string $needleSQL, string $haystackSQL, string $message = '', bool $ignoreCase = false, bool $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 = [])

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

static TempDatabase tempDB()

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 string get_fixture_file()

Return Value

string

bool getUsesDatabase()

Return Value

bool

bool getUsesTransactions()

Return Value

bool

array getRequireDefaultRecordsFrom()

Return Value

array

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

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

FixtureFactory|false getFixtureFactory() deprecated

deprecated 4.0.0:5.0.0

Return Value

FixtureFactory|false

$this setFixtureFactory(FixtureFactory $factory) deprecated

deprecated 4.0.0:5.0.0

Sets a new fixture factory

Parameters

FixtureFactory $factory

Return Value

$this

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

clearFixtures()

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

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

Parameters

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

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

Parameters

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

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 {@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);

assertDOSContains($matches, $dataObjectSet) deprecated

deprecated 4.0.0:5.0.0 Use assertListContains() instead

Parameters

$matches
$dataObjectSet

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);

static assertNotDOSContains($matches, $dataObjectSet) deprecated

deprecated 4.0.0:5.0.0 Use assertListNotContains() instead

Parameters

$matches
$dataObjectSet

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

assertDOSEquals($matches, SS_List $dataObjectSet) deprecated

deprecated 4.0.0:5.0.0 Use assertListEquals() instead

Parameters

$matches
SS_List $dataObjectSet

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

assertDOSAllMatch($match, SS_List $dataObjectSet) deprecated

deprecated 4.0.0:5.0.0 Use assertListAllMatch() instead

Parameters

$match
SS_List $dataObjectSet

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

Asserts that two SQL queries are equivalent

Parameters

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

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

Asserts that a SQL query contains a SQL fragment

Parameters

string $needleSQL
string $haystackSQL
string $message
bool $ignoreCase
bool $checkForObjectIdentity

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

Asserts that a SQL query contains a SQL fragment

Parameters

string $needleSQL
string $haystackSQL
string $message
bool $ignoreCase
bool $checkForObjectIdentity

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

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

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

Session session()

Returns the {@link Session} object for this test

Return Value

Session

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 = [])

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

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

PHPUnit_Framework_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

PHPUnit_Framework_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

PHPUnit_Framework_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

PHPUnit_Framework_AssertionFailedError

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

static bool get_disable_themes()

Return Value

bool

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