1. class
  2. SilverStripe
  3. \
  4. Dev
  5. \
  6. SapphireTest

SapphireTest

class SapphireTest extends TestCase implements TestOnly

Test case class for the Sapphire framework.

Sapphire unit testing is based on PHPUnit, but provides a number of hooks into our data model that make it easier to work with.

This class should not be used anywhere outside of unit tests, as phpunit may not be installed in production sites.

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|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.

FixtureFactory|false
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, string $message = '', bool $ignoreCase = false, bool $checkForObjectIdentity = true, bool $checkForNonObjectIdentity = false)

No description

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

No description

bool
clearEmails()

Clear the log of emails sent

static array
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(array $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 = '', int $delta, 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

Details

at line 174
static TempDatabase tempDB()

Return Value

TempDatabase

at line 187
static array getIllegalExtensions()

Gets illegal extensions for this class

Return Value

array

at line 197
static array getRequiredExtensions()

Gets required extensions for this class

Return Value

array

at line 226
static string|string[] get_fixture_file()

Return Value

string|string[]

at line 234
bool getUsesDatabase()

Return Value

bool

at line 242
bool getUsesTransactions()

Return Value

bool

at line 250
array getRequireDefaultRecordsFrom()

Return Value

array

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

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

at line 418
FixtureFactory|false getFixtureFactory() deprecated

deprecated 4.0.0:5.0.0

Return Value

FixtureFactory|false

at line 432
$this setFixtureFactory(FixtureFactory $factory) deprecated

deprecated 4.0.0:5.0.0

Sets a new fixture factory

Parameters

FixtureFactory $factory

Return Value

$this

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

at line 526
clearFixtures()

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

at line 588
static assertContains($needle, $haystack, string $message = '', bool $ignoreCase = false, bool $checkForObjectIdentity = true, bool $checkForNonObjectIdentity = false)

Parameters

$needle
$haystack
string $message
bool $ignoreCase
bool $checkForObjectIdentity
bool $checkForNonObjectIdentity

at line 609
static assertNotContains($needle, $haystack, string $message = '', bool $ignoreCase = false, bool $checkForObjectIdentity = true, bool $checkForNonObjectIdentity = false)

Parameters

$needle
$haystack
string $message
bool $ignoreCase
bool $checkForObjectIdentity
bool $checkForNonObjectIdentity

at line 635
bool clearEmails()

Clear the log of emails sent

Return Value

bool True if emails cleared

at line 656
static array 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 Contains keys: 'Type', 'To', 'From', 'Subject', 'Content', 'PlainContent', 'AttachedFiles', 'HtmlContent'

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

at line 725
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 = sam@example.com: $this->assertListContains(['Email' => '...@example.com'], $members);

Check that $members includes entries with Email = sam@example.com and with Email = ingo@example.com: $this->assertListContains([ ['Email' => '...@example.com'], ['Email' => 'i...@example.com'], ], $members);

at line 749
assertDOSContains(array $matches, $dataObjectSet) deprecated

deprecated 4.0.0:5.0.0 Use assertListContains() instead

Parameters

array $matches
$dataObjectSet

at line 775
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 = sam@example.com: $this->assertListNotContains(['Email' => '...@example.com'], $members);

Check that $members doesn't have entries with Email = sam@example.com and with Email = ingo@example.com: $this->assertListNotContains([ ['Email' => '...@example.com'], ['Email' => 'i...@example.com'], ], $members);

at line 803
static assertNotDOSContains($matches, $dataObjectSet) deprecated

deprecated 4.0.0:5.0.0 Use assertListNotContains() instead

Parameters

$matches
$dataObjectSet

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

at line 851
assertDOSEquals($matches, SS_List $dataObjectSet) deprecated

deprecated 4.0.0:5.0.0 Use assertListEquals() instead

Parameters

$matches
SS_List $dataObjectSet

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

at line 895
assertDOSAllMatch($match, SS_List $dataObjectSet) deprecated

deprecated 4.0.0:5.0.0 Use assertListAllMatch() instead

Parameters

$match
SS_List $dataObjectSet

at line 924
static assertSQLEquals(string $expectedSQL, string $actualSQL, string $message = '', int $delta, int $maxDepth = 10, bool $canonicalize = false, bool $ignoreCase = false)

Asserts that two SQL queries are equivalent

Parameters

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

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

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

at line 987
static start()

Start test environment

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

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

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

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

at line 1142
logOut()

Log out the current user

at line 1201
static array getExtraDataObjects()

Return all extra objects to scaffold for this test

Return Value

array

at line 1211
static array getExtraControllers()

Get additional controller classes to register routes for

Return Value

array