INTERPRETING.md

Interpreting Test262 Tests

All tests are declared as text files located within this project's test directory. In order to execute Test262 tests, runtimes must observe the following semantics.

Note When these instructions change in any substantive way, the version property of the JSON-formatted package.json file will be incremented. In this way, consumers who are transitioning between revisions of Test262 can more easily determine the cause of new test failures.

Test Execution

Test262 tests are only valid under the runtime environment conditions described here. Test environments may be further modified according to the metadata contained with each test--refer to the Metadata section for more details.

Realm Isolation

Each test must be executed in a new ECMAScript realm dedicated to that test. Unless configured otherwise (via the module flag), source text must be interpreted as global code.

Test262-Defined Bindings

The contents of the following files must be evaluated in the test realm's global scope prior to test execution:

1. harness/assert.js
2. harness/sta.js

Host-Defined Functions

The following values must be defined as writable, configurable, non-enumerable properties of the global scope prior to test execution.

• print A function that exposes the string value of its first argument to the test runner. This is used as a communication mechanism for asynchronous tests (via the async flag, described below).
• $262 An ordinary object with the following properties:

  • createRealm - a function which creates a new ECMAScript Realm, defines this API on the new realm's global object, and returns the $262 property of the new realm's global object

  • detachArrayBuffer - a function which implements the DetachArrayBuffer abstract operation

  • evalScript - a function which accepts a string value as its first argument and executes is as an ECMAScript script according to the following algorithm:

    1. Let hostDefined be any host-defined values for the provided
       sourceText (obtained in an implementation dependent manner)
    2. Let realm be the current Realm Record.
    3. Let s be ParseScript(sourceText, realm, hostDefined).
    4. If s is a List of errors, then
       a. Let error be the first element of s.
       b. Return
          Completion{[[Type]]: throw, [[Value]]: error, [[Target]]: empty}.
    5. Let status be ScriptEvaluation(s).
    6. Return Completion(status).

  • global - a reference to the global object on which $262 was initially defined

  • IsHTMLDDA - (present only in implementations that can provide it) an object that 1) has an IsHTMLDDA internal slot, and 2) when called with no arguments or with the single argument "" returns null. Use this property to test that ECMAScript algorithms aren't mis-implemented to treat document.all as being undefined or of type Undefined (instead of Object). (The peculiar second requirement permits testing algorithms when they also call document.all with such arguments, so that testing for correct behavior requires knowing how the call behaves. This is rarely necessary.) Tests using this function must be tagged with the IsHTMLDDA feature so that only hosts supporting this property will run them.

  • agent - an ordinary object with the following properties:

    • start - a function that takes a script source string and runs the script in a concurrent agent. Will block until that agent is running. The agent has no representation. The agent script will be run in an environment that has an object $262 with a property agent with the following properties:
      • receiveBroadcast - a function that takes a function and calls the function when it has received a broadcast from the parent, passing it the broadcast as two arguments, a SharedArrayBuffer and an Int32. This function may return before a broadcast is received (eg to return to an event loop to await a message) and no code should follow the call to this function.
      • report - a function that accepts a single "message" argument, which is converted to a string* and placed in a transmit queue whence the parent will retrieve it. Messages should be short. (* Note that string conversion has been implicit since the introduction of this host API, but is now explicit.)
      • sleep - a function that takes a millisecond argument and sleeps the agent for approximately that duration.
      • leaving - a function that signals that the agent is done and may be terminated (if possible).
      • monotonicNow - a function that returns a value that conforms to DOMHighResTimeStamp and is produced in such a way that its semantics conform to Monotonic Clock.
    • broadcast - a function that takes a SharedArrayBuffer and an Int32 and broadcasts the two values to all concurrent agents. The function blocks until all agents have retrieved the message. Note, this assumes that all agents that were started are still running.
    • getReport - a function that reads an incoming string from any agent, and returns it if it exists, or returns null otherwise.
    • sleep - a function that takes a millisecond argument and sleeps the execution for approximately that duration.
    • monotonicNow - a function that returns a value that conforms to DOMHighResTimeStamp and is produced in such a way that its semantics conform to Monotonic Clock.

Normative references

DOMHighResTimeStamp, Monotonic Clock
Ilya Grigorik, James Simonsen, Jatinder Mann.
High Resolution Time Level 2 March 2018. W3C. URL: https://www.w3.org/TR/hr-time-2/

Strict Mode

Unless configured otherwise (via the noStrict, onlyStrict, module, or raw flags), each test must be executed twice: once in ECMAScript's non-strict mode, and again in ECMAScript's strict mode. To run in strict mode, the test contents must be modified prior to execution--a "use strict" directive must be inserted as the initial character sequence of the file, followed by a semicolon (;) and newline character (\n):

"use strict";

This must precede any additional text modifications described by test metadata.

Modules