abstract class SapphireTest extends TestCase implements TestOnly (View source)

Test case class for the Silverstripe 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.

Properties

protected static string|array $fixture_file

Path to fixture data for this test run.

protected bool $usesDatabase
protected bool $usesTransactions

This test will cleanup its state via transactions.

protected static bool $is_running_test
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.

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.

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.

protected static array $extra_dataobjects

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

protected static array $extra_controllers

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

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.

protected static SapphireTestState $state

State management container for SapphireTest

protected static TempDatabase $tempDB

Temp database helper

protected FixtureFactory|bool $fixtureFactory
protected $cache_generatedMembers

Cache for logInWithPermission()

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

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