(info) This AI is still in early stages of development.

REQUIRE( )

Owned by Aubergine
Last updated: Nov 24, 2012Version comment
2 min read
Check whether a test or group of tests have passed. If the requirement fails, a RequireSignal will be sent which terminates the current test and marks it as failed.

 

Syntax

REQUIRE( requirement );

Parameters

ParameterTypeMandatoryNotesAPI Version
requirementString(tick)

The requirement to check – see requirement types below for more details.

If the requirement is not met, a signal will be sent to abort the current test.

1.0

Requirement types

requirementNotesAPI Version
"testName"

Checks a specific test, specified by it's name, to see if it passed.

Example: REQUIRE( "My Tests" );

If the test is not yet defined, not started, still in progress or failed, the requirement will fail.

1.0
"^"

Checks the previous test in the queue to see if it passed.

Example: REQUIRE( "^" );

Note: Test.APPEND( ) tests don't get queued.

If the test is still in progress or failed, the requirement will fail.

1.1
"@"

Checks to see if all tests (that have been performed) in the current module have passed so far.

Example: REQUIRE( "@" );

If any of the tests in the module have failed, the requirement will fail.

1.1
"@^"

Checks to see if all tests in the previous module have passed.

Example: REQUIRE( "@^" );

Note: The previous module is the last module to be defined before the current module was defined.

If any of the tests in the module failed, the requirement will fail.

1.1
"@module/path/"

Specify a module path, prefixed by "@", to check if all tests (if any) in modules starting with that path have passed.

Example: REQUIRE( "@Tests/" ); would check if all tests in all modules starting with "Tests/" have passed.

If any test in the matching modules failed, the requirement will fail.

1.1
"*"

Check if all invoked tests have passed so far.

Example: REQUIRE( "*" );

Note: Unless you know exactly which test scripts have run prior to the script containing your tests, using this could give unexpected results. For example, the script that tests the Test API generates some failures by design (to check that tests fail where expected).

If one or more tests have failed, the requirement will fail.

1.1

Return values

ValueTypeNotesAPI Version
<error>ErrorMost likely the parameters are wrong.1.0
<signal>RequireSignal

Forces the current unit test to abort, marking it as failed in the process.

(warning) Do not catch the RequireSignal otherwise it will have no effect. 

1.0
trueBooleanThe specified requirement was met.1.0

Example

Test("Chat() defined", Test.EXPECT( 1 ), function() {
	if (!hasNative( "chat", "chat() defined" )) {
		ABORT( "Unable to test chat system" );
	}
})
 
Test("Send a chat message", Test.ANY( ), function() {
	REQUIRE( "Chat() defined" ); // will abort if that test failed
 
	// do further testing of chat() here
});
REQUIRE( ) is not related to Dependency Checking.
Availability STABLE

Requires:

Contents

Jump to:

Test API

Topics:

  • Test() — Define a unit test and it's configuration...
  • Test Modules — A test module groups one or more unit tests and provides additional lifecycle settings for those tests...
  • Test Modes — Defines the mode in which a unit test is run...
    • Test.ANY( ) — The most basic unit test mode...
    • Test.EXPECT( ) — Causes the test to fail if it does not generate the specified number of results...
    • Test.ASYNCH( ) — Causes a test to keep running until it either passes, fails or times-out...
    • Test.APPEND( ) — Appends results to a specific asynchronous test session...
  • Unit Tests — The unit test function, responsible for performing one or more Test Assertions...
  • Test Assertions — Assertions are used to perform various tests and annotations within a unit test...
    • comment( ) — Adds a comment to the test results...
    • ok( ) — A simple state checking assertion...
    • hasNative( ) — Assert presence of a native property on the global object...
    • hasFunction( ) — Check if a context has a function property, optionally with specified number of formal parameters...
    • equal( ) — A basic equality checking assertion...
    • notEqual( ) — A basic inequality checking assertion...
    • strictEqual( ) — A strict equality checking assertion...
    • notStrictEqual( ) — A strict inequality checking assertion...
    • deepEqual( ) — A deep equality checking assertion...
    • notDeepEqual( ) — A deep inequality checking assertion...
    • similarTo( ) — A deep similarity checking assertion...
    • notSimilarTo( ) — A deep dissimilarity spotting assertion...
  • Test Signals — Signals are used to prematurely terminate Unit Tests...
    • REQUIRE( ) — Check whether a test or group of tests have passed. If the requirement fails, a RequireSignal will be sent which terminates the current test and marks it as failed.
    • ABORT( ) — Aborts the current test, marking it as failed in the process...
    • FINISH( ) — Terminates the test as if it had finished normally...
  • Test Events — Events defined by Test API...
  • Test Results — After testing is finished, output results...
  • Test API - Dev Notes — Developer notes for this API...