class SapphireTest extends PHPUnit_Framework_TestCase implements TestOnly (View source)

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

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