◁ API Extensions ≡ Table of Contents Development ▷
The Test API supports implementation and execution of integration tests. It can be used for suites, scenarios and single test cases.
As a modular part of Seanox aspect-js, the Test API is included in all releases except the core versions. Because it changes error handling and console output, it must be activated explicitly at runtime.
Test.activate();
Test.create({test() {
...
}});
Test.start();
The smallest component in an integration test is called task because case is a JavaScript keyword. A task can be implemented alone, but is always used in a scenario.
Test.activate();
Test.create({test() {
Assert.assertTrue(true);
}});
Test.start();
Task is primarily a meta-object.
{name:..., test:..., timeout:..., expected:..., ignore:...}
Optional name of the test task.
An implemented method to be executed as a test.
Optional maximum runtime of the test item in milliseconds. Exceeding this limit causes the test to fail. A value greater than 0 is expected; otherwise the timeout is ignored.
Optional definition for expected errors. The error must occur for the test to be successful. The value must be an error object or a RegExp.
Optional true if the test is to be ignored.
A scenario is a sequence of test cases (tasks).
Test.activate();
Test.create({test() {
Assert.assertTrue(true);
}});
Test.create({name:"example", timeout:1000, test() {
Assert.assertTrue(true);
}});
Test.create({expected: Error, test() {
throw new Error();
}});
Test.create({expected: /^My Error/i, test() {
throw new Error("My Error");
}});
Test.create({ignore:true, test() {
Assert.assertTrue(true);
}});
Test.start();
A suite is a bundle of test cases, scenarios and other suites. A suite often consists of different files that represent a complex test. A cascade of files allows the test to start in any file and place. This supports integration tests on different levels and with different complexity.
Test cases are implemented with assertions. The Test API provides elementary
assertions, and additional assertions can be implemented. If an assertion is not
true, an error is thrown, optionally with an individual error message.
The methods use different signatures, which are described in the examples below.
Asserts that a value is true.
Assert.assertTrue(true);
Assert.assertTrue("message", true);
Asserts that a value is false, as negation of Assert.assertTrue(...).
Assert.assertFalse(false);
Assert.assertFalse("message", false);
Asserts that two values are equals.
Difference between equals and same: === / == or !== / !=
Assert.assertEquals(expected, value);
Assert.assertEquals("message", expected, value);
Asserts that two values are not equals, as negation of Assert.assertEquals(...).
Difference between equals and same: === / == or !== / !=
Assert.assertNotEquals(unexpected, value);
Assert.assertNotEquals("message", unexpected, value);
Asserts that two values are the same.
Difference between equals and same: === / == or !== / !=
Assert.assertSame(expected, value);
Assert.assertSame("message", expected, value);
Asserts two values are not the same, as negation of Assert.assertSame(...).
Difference between equals and same: === / == or !== / !=
Assert.assertNotSame(unexpected, value);
Assert.assertNotSame("message", unexpected, value);
Asserts that a value is null.
Assert.assertNull(null);
Assert.assertNull("message", null);
Asserts that a value is not null, as negation of Assert.assertNull(...).
Assert.assertNotNull("value");
Assert.assertNotNull("message", "value");
Asserts that a value is undefined.
Assert.assertUndefined(undefined);
Assert.assertUndefined("message", undefined);
Asserts that a value is not undefined, as negation of Assert.assertUndefined(...).
Assert.assertNotUndefined("value");
Assert.assertNotUndefined("message", "value");
Fails a test with an optional message.
Assert.fail();
Assert.fail("message");
Optionally, the Test API can be configured with each start. A meta-object is expected as parameter. The configuration contained in it is partially adopted and the unknown is ignored.
Test.start({auto: boolean, output: {...}, monitor: {...}});
Option that triggers the start when loading the page. If the page is already loaded, the parameter auto is ignored and the start is executed immediately.
Test.start({auto: true});
Function or object for outputting messages and errors. If not specified, console object is used.
Test.start({output: {
log(message) {
...
},
error(message) {
...
}
}});
Monitors the progress of the test and is informed of the various steps and statuses during execution. The monitor can also be used for data output, for example, to redirect the output to a DOM element. The monitor is optional. Without this, the console is used to output information about the test process.
Test.start({monitor: {
start(status) {
The method is called with the start.
},
suspend(status) {
The method is called with suspension.
},
resume(status) {
The method is called if the test run is stopped and is to be
continued later.
},
interrupt(status) {
The method is called if you want to abort the test run.
The test run cannot then be resumed.
},
perform(status) {
The method is called before a test task is performed.
},
response(status) {
The method is called when a test task has been performed.
Here you can find the result of the test task.
},
finish(status) {
The method is called when all test tasks have been completed.
}
}});
The current status is passed to all monitor methods as an meta-object. The status contains details of the current task and the queue. The details are read-only and cannot be changed.
{
task: {
title:
title of the test task,
meta:
meta information about the test itself (name, test,
timeout, expected, serial),
running:
indicator when the test task is in progress
timing:
start time from the test task in milliseconds
timeout:
optional, the time in milliseconds when a timeout is
expected
duration:
total execution time of the test task in milliseconds, is
set with the end of the test task
error:
optional, if an unexpected error (also assertion error) has
occurred, which terminated the test task
},
queue: {
timing:
start time in milliseconds,
size:
original queue length,
length:
number of outstanding tests,
progress:
number of tests performed,
lock:
indicator when a test is performed and the queue is waiting,
faults:
number of detected faults
}
}
As a development tool, browsers provide console output that can be used to log
information, for which different channels or levels are supported:
LOG, WARN, ERROR, INFO
console.log(message);
console.warn(message);
console.error(message);
console.info(message);
To be able to include console output in tests, the activated Test API supports forwarding, listeners and buffers for console output.
The forwarding runs completely in the background and distributes the output to the browser console output and to the components of the Test API. In the case of (I)Frames, the output is forwarded to enclosing or superordinate window-objects and is accessible there via buffer and listener with an activated Test API.
When the Test API is enabled, the console object of the JavaScript API is extended by the buffer output. The buffer contains caches for the levels: LOG, WARN, ERROR and INFO as well as methods for emptying.
const log = console.output.log;
const warn = console.output.warn;
const error = console.output.error;
const info = console.output.info;
console.output.clear();
Callback methods can be established as listeners for console output.
console.listen(function(level, ...parameters) {
const message = parameters[0];
...
});
The callback methods are then called at each console output and the log level is
passed as the first parameter. The additional number of parameters is variable
and depends on the initial call of the corresponding console methods. Which
often makes it easier to use the spread syntax ....
Monitoring monitors the progress of the test and is informed of the various steps and statuses during execution. The monitor is optional. Without this, the console is used to output information about the test process.
Details about configuration and usage are described in chapter Configuration - monitor.
The test progress and the execution of the tests can be controlled by the Test API.
Test.start();
Test.start({auto: boolean});
The start can be done manually or when using auto = true, by loading the
page. If the page is already loaded, the parameter auto is ignored and the
start is executed immediately.
Test.suspend();
Suspends the current test execution, which can be continued from the current
test with Test.resume().
Test.resume();
Continues the test execution if it was stopped before.
Test.interrupt();
Interrupts the current test run and discards all outstanding tests.
The test run can be restarted with Test.start().
Test.status();
Returns a snapshot of the status of the current test. The status contains details of the current task and the queue. The details are read-only and cannot be changed. If no test is executed, false is returned.
{
task: {
title:
title of the test task,
meta:
meta information about the test itself (name, test,
timeout, expected, serial),
running:
indicator when the test task is in progress
timing:
start time from the test task in milliseconds
timeout:
optional, the time in milliseconds when a timeout is
expected
duration:
total execution time of the test task in milliseconds, is
set with the end of the test task
error:
optional, if an unexpected error (also asser error) has
occurred, which terminated the test task
},
queue: {
timing:
start time in milliseconds,
size:
original queue length,
length:
number of outstanding tests,
progress:
number of tests performed,
lock:
indicator when a test is performed and the queue is waiting,
faults:
number of detected faults
}
}
Events and their callback methods are another way of monitoring test execution. The callback methods are registered at the Test API for corresponding events and then work similar to the monitor.
List of available events:
Test.EVENT_INTERRUPT
Test.EVENT_PERFORM
Test.EVENT_RESPONSE
Test.EVENT_RESUME
Test.EVENT_START
Test.EVENT_SUSPEND
Examples of use:
Test.listen(Test.EVENT_START, function(event, status) {
...
});
Test.listen(Test.EVENT_PERFORM, function(event, status) {
...
});
Test.listen(Test.EVENT_FINISH, function(event, status) {
...
});
The Test API also activates extensions of the JavaScript API.
Method that simulates keyboard input for element objects. The following events are triggered during simulation: focus, keydown, keyup, change
<form action="/api/example" method="POST">
<input type="text" id="inputText"/>
<input type="submit"/>
</form>
document.querySelector("#inputText").typeValue("Hello World!");
The method will overwrite an existing value in the element by default. However,
if the simulated input is to be added, overwriting can be deactivated with the
clear parameter.
document.querySelector("#inputText").typeValue("Hello World!", false);
Method that creates a simple string for an element object. The string is based
on Element.prototype.outerHTML.
<form action="/api/example" method="POST">
<input type="text" id="inputText"/>
<input type="submit"/>
</form>
console.log(document.querySelector("form").toPlainString());
Output:
<form xmlns="http://www.w3.org/1999/xhtml" action="/api/example" method="POST">
<input type="text" id="inputText"/>
<input type="submit"/>
</form>
Method to trigger an event for an element with the optional parameters bubbles
(default: false) and cancelable (default: true).
document.querySelector("#button").trigger("click");
document.querySelector("#button").trigger("click", true);
document.querySelector("#button").trigger("click", true, false);
Method that creates a simple string for a node object. The string is based on
XMLSerializer.serializeToString(node).
const text = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"
+ "<note>"
+ " <to>Tove</to>"
+ " <from>Jani</from>"
+ " <heading>Reminder</heading>"
+ " <body>Don't forget me this weekend!</body>"
+ "</note>";
const parser = new DOMParser();
const xml = parser.parseFromString(text, "text/xml");
const nodes = xml.evaluate("/note", xml, null, XPathResult.ANY_TYPE, null);
const result = nodes.iterateNext();
console.log(result.toPlainString());
Output:
<note><to>Tove</to><from>Jani</from><heading>Reminder</heading><body>Don't forget me this weekend!</body></note>
Method that creates a simple string for an object. The string is based on
JSON.stringify(object).
const example = {a:1, b:2, c() {return;}};
console.log(example.toPlainString());
Output:
{"a":1,"b":2}