Page MenuHomePhorge
Diviner Arcanist Tech Docs PhutilTestCase

abstract class PhutilTestCase
Arcanist Technical Documentation (Unit Testing)

Base test case for the very simple libphutil test framework.

Tasks

Making Test Assertions

  • final protected function assertFalse($result, $message) — Assert that a value is `false`, strictly. The test fails if it is not.
  • final protected function assertTrue($result, $message) — Assert that a value is `true`, strictly. The test fails if it is not.
  • final protected function assertEqual($expect, $result, $message) — Assert that two values are equal, strictly. The test fails if they are not.
  • final protected function assertFailure($message) — Assert an unconditional failure. This is just a convenience method that better indicates intent than using dummy values with assertEqual(). This causes test failure.
  • final protected function assertSkipped($message) — End this test by asserting that the test should be skipped for some reason.

Exception Handling

  • final protected function assertException($expected_exception_class, $callable) — This simplest way to assert exceptions are thrown.
  • final protected function tryTestCases($inputs, $expect, $callable, $exception_class) — Straightforward method for writing unit tests which check if some block of code throws an exception. For example, this allows you to test the exception behavior of ##is_a_fruit()## on various inputs:
  • final protected function tryTestCaseMap($map, $callable, $exception_class) — Convenience wrapper around @{method:tryTestCases} for cases where your inputs are scalar. For example:

Hooks for Setup and Teardown

  • protected function willRunTests() — This hook is invoked once, before any tests in this class are run. It gives you an opportunity to perform setup steps for the entire class.
  • protected function didRunTests() — This hook is invoked once, after any tests in this class are run. It gives you an opportunity to perform teardown steps for the entire class.
  • protected function willRunOneTest($test_method_name) — This hook is invoked once per test, before the test method is invoked.
  • protected function didRunOneTest($test_method_name) — This hook is invoked once per test, after the test method is invoked.
  • public function willRunTestCases($test_cases) — This hook is invoked once, before any test cases execute. It gives you an opportunity to perform setup steps for the entire suite of test cases.
  • public function didRunTestCases($test_cases) — This hook is invoked once, after all test cases execute.

Internals

  • final public function __construct() — Construct a new test case. This method is ##final##, use willRunTests() to provide test-wide setup logic.
  • private function failTest($reason) — Mark the currently-running test as a failure.
  • private function passTest($reason) — This was a triumph. I'm making a note here: HUGE SUCCESS.
  • private function skipTest($reason) — Mark the current running test as skipped.
  • final public function run() — Execute the tests in this test case. You should not call this directly; use @{class:PhutilUnitTestEngine} to orchestrate test execution.
  • private function failAssertionWithExpectedValue($expect_description, $actual_result, $message) — Fail an assertion which checks that some result is equal to a specific value, like 'true' or 'false'. This prints a readable error message and fails the current test.

Other Methods

Methods

public function __get($name)
Inherited

This method is not documented.
Parameters
$name
Return
wild

public function __set($name, $value)
Inherited

This method is not documented.
Parameters
$name
$value
Return
wild

public function current()
Inherited

This method is not documented.
Return
wild

public function key()
Inherited

This method is not documented.
Return
wild

public function next()
Inherited

This method is not documented.
Return
wild

public function rewind()
Inherited

This method is not documented.
Return
wild

public function valid()
Inherited

This method is not documented.
Return
wild

private function throwOnAttemptedIteration()
Inherited

This method is not documented.
Return
wild

public function getPhobjectClassConstant($key, $byte_limit)
Inherited

Phobject

Read the value of a class constant.

This is the same as just typing self::CONSTANTNAME, but throws a more useful message if the constant is not defined and allows the constant to be limited to a maximum length.

Parameters
string$keyName of the constant.
int|null$byte_limitMaximum number of bytes permitted in the value.
Return
stringValue of the constant.

final protected function assertFalse($result, $message)

Assert that a value is false, strictly. The test fails if it is not.

Parameters
wild$resultThe empirically derived value, generated by executing the test.
string$messageA human-readable description of what these values represent, and particularly of what a discrepancy means.
Return
void

final protected function assertTrue($result, $message)

Assert that a value is true, strictly. The test fails if it is not.

Parameters
wild$resultThe empirically derived value, generated by executing the test.
string$messageA human-readable description of what these values represent, and particularly of what a discrepancy means.
Return
void

final protected function assertEqual($expect, $result, $message)

Assert that two values are equal, strictly. The test fails if they are not.

NOTE: This method uses PHP's strict equality test operator (===) to compare values. This means values and types must be equal, key order must be identical in arrays, and objects must be referentially identical.
Parameters
wild$expectThe theoretically expected value, generated by careful reasoning about the properties of the system.
wild$resultThe empirically derived value, generated by executing the test.
string$messageA human-readable description of what these values represent, and particularly of what a discrepancy means.
Return
void

final protected function assertFailure($message)

Assert an unconditional failure. This is just a convenience method that better indicates intent than using dummy values with assertEqual(). This causes test failure.

Parameters
string$messageHuman-readable description of the reason for test failure.
Return
void

final protected function assertSkipped($message)

End this test by asserting that the test should be skipped for some reason.

Parameters
string$messageReason for skipping this test.
Return
void

final protected function assertCaught($expect, $actual, $message)

This method is not documented.
Parameters
$expect
$actual
$message
Return
wild

final protected function assertException($expected_exception_class, $callable)

This simplest way to assert exceptions are thrown.

Parameters
exception$expected_exception_classThe expected exception.
callable$callableThe thing which throws the exception.
Return
void

final protected function tryTestCases($inputs, $expect, $callable, $exception_class)

Straightforward method for writing unit tests which check if some block of code throws an exception. For example, this allows you to test the exception behavior of is_a_fruit() on various inputs:

public function testFruit() {
  $this->tryTestCases(
    array(
      'apple is a fruit'    => new Apple(),
      'rock is not a fruit' => new Rock(),
    ),
    array(
      true,
      false,
    ),
    array($this, 'tryIsAFruit'),
    'NotAFruitException');
}

protected function tryIsAFruit($input) {
  is_a_fruit($input);
}
Parameters
map$inputsMap of test case labels to test case inputs.
list$expectList of expected results, true to indicate that the case is expected to succeed and false to indicate that the case is expected to throw.
callable$callableCallback to invoke for each test case.
string$exception_classOptional exception class to catch, defaults to 'Exception'.
Return
void

final protected function tryTestCaseMap($map, $callable, $exception_class)

Convenience wrapper around tryTestCases() for cases where your inputs are scalar. For example:

public function testFruit() {
  $this->tryTestCaseMap(
    array(
      'apple' => true,
      'rock'  => false,
    ),
    array($this, 'tryIsAFruit'),
    'NotAFruitException');
}

protected function tryIsAFruit($input) {
  is_a_fruit($input);
}

For cases where your inputs are not scalar, use tryTestCases().

Parameters
map$mapMap of scalar test inputs to expected success (true expects success, false expects an exception).
callable$callableCallback to invoke for each test case.
string$exception_classOptional exception class to catch, defaults to 'Exception'.
Return
void

protected function willRunTests()

This hook is invoked once, before any tests in this class are run. It gives you an opportunity to perform setup steps for the entire class.

Return
void

protected function didRunTests()

This hook is invoked once, after any tests in this class are run. It gives you an opportunity to perform teardown steps for the entire class.

Return
void

protected function willRunOneTest($test_method_name)

This hook is invoked once per test, before the test method is invoked.

Parameters
string$test_method_nameMethod name of the test which will be invoked.
Return
void

protected function didRunOneTest($test_method_name)

This hook is invoked once per test, after the test method is invoked.

Parameters
string$test_method_nameMethod name of the test which was invoked.
Return
void

public function willRunTestCases($test_cases)

This hook is invoked once, before any test cases execute. It gives you an opportunity to perform setup steps for the entire suite of test cases.

Parameters
list<PhutilTestCase>$test_casesList of test cases to be run.
Return
void

public function didRunTestCases($test_cases)

This hook is invoked once, after all test cases execute.

Parameters
list<PhutilTestCase>$test_casesList of test cases that ran.
Return
void

final public function __construct()

Construct a new test case. This method is final, use willRunTests() to provide test-wide setup logic.

Return
this//Implicit.//

private function failTest($reason)

Mark the currently-running test as a failure.

Parameters
string$reasonHuman-readable description of problems.
Return
void

private function passTest($reason)

This was a triumph. I'm making a note here: HUGE SUCCESS.

Parameters
string$reasonHuman-readable overstatement of satisfaction.
Return
void

private function skipTest($reason)

Mark the current running test as skipped.

Parameters
string$reasonDescription for why this test was skipped.
Return
void

private function resultTest($test_result, $reason)

This method is not documented.
Parameters
$test_result
$reason
Return
wild

final public function run()

Execute the tests in this test case. You should not call this directly; use PhutilUnitTestEngine to orchestrate test execution.

Return
void

final public function setEnableCoverage($enable_coverage)

This method is not documented.
Parameters
$enable_coverage
Return
wild

private function beginCoverage()

This method is not documented.
Return
wild

private function endCoverage()

This method is not documented.
Return
wild

private function assertCoverageAvailable()

This method is not documented.
Return
wild

final public function getWorkingCopy()

This method is not documented.
Return
wild

final public function setWorkingCopy($working_copy)

This method is not documented.
Parameters
ArcanistWorkingCopyIdentity$working_copy
Return
wild

final public function getProjectRoot()

This method is not documented.
Return
wild

final public function setPaths($paths)

This method is not documented.
Parameters
array$paths
Return
wild

final protected function getLink($method)

This method is not documented.
Parameters
$method
Return
wild

final public function setRenderer($renderer)

This method is not documented.
Parameters
ArcanistUnitRenderer$renderer
Return
wild

private static function getCallerInfo()

Returns info about the caller function.

Return
map

private function failAssertionWithExpectedValue($expect_description, $actual_result, $message)

Fail an assertion which checks that some result is equal to a specific value, like 'true' or 'false'. This prints a readable error message and fails the current test.

This method throws and does not return.

Parameters
string$expect_descriptionHuman readable description of the expected value.
string$actual_resultThe actual value.
string|null$messageOptional assertion message.
Return
void

final protected function assertExecutable($binary)

This method is not documented.
Parameters
$binary
Return
wild

final protected function getSupportExecutable($executable)

This method is not documented.
Parameters
$executable
Return
wild
Defined
src/unit/engine/phutil/PhutilTestCase.php:11
Extends
Phobject
Content licensed under Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA) unless otherwise noted; code licensed under Apache 2.0 or other open source licenses. · CC BY-SA 4.0 · Apache 2.0