Skip to content

feat(docs): Add documentation resources for Test Starter and Manifest #86

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat(docs): Add documentation resources for Test Starter and Manifest #86

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
131 changes: 131 additions & 0 deletions resources/docs/1.136.7/22f50c0f0b104bf3ba84620880793d3f.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
# Concept and Basic Setup

To apply the test starter concept to your SAPUI5 project, you need to create a test suite and a generic test page that allows for the running of one or multiple test modules.

> ### Note:
> For SAPUI5 applications, the test suite and the generic test page are typically placed in the `webapp/test` folder. The code samples in the next sections use `<NAMESPACE>` as a placeholder for your SAPUI5 project namespace. Please replace this placeholder with your SAPUI5 project namespace defined in the `sap.app/id` property in the `manifest.json` file by replacing the '.' with '/', for example `my.ui5app` becomes `my/ui5app`. However, for the `<NAMESPACE-WITH-DOTS>` in `data-sap-ui-resource-roots`, use the exact value of `sap.app/id` \(separated by dots\).

## The UI5 Test Suite

A test suite configures the environment for the tests. It consists of a `*.qunit.html` page often named `testsuite.qunit.html` and a corresponding `*.qunit.js` module.

The default naming convention for the test suite is `testsuite.qunit.html` and `testsuite.qunit.js`.

There can be multiple test suites in a project. When adding more test suites, the naming must follow the pattern `testsuite.<name>.qunit.html` / `testsuite.<name>.qunit.js`.

### The UI5 Test Suite Page

The test suite page uses the `sap/ui/test/starter/createSuite.js` script to initialize the test suite in a way which is compliant to the content security policy, based on the externalized test configuration provided in the test suite module.

Unlike with the UI5 bootstrap, this script only accepts a limited set of configuration options:

- The `data-sap-ui-testsuite` attribute specifies the test suite module.

- The`data-sap-ui-resource-roots` attribute registers the project-specific namespaces, allowing the test suite modules to load from the correct locations. Note that, unlike module names, this configuration requires namespaces to be separated by dots.

```

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>QUnit test suite for NAMESPACE</title>
<script
src="../resources/sap/ui/test/starter/createSuite.js"
data-sap-ui-testsuite="test-resources/<NAMESPACE>/testsuite.qunit"
data-sap-ui-resource-roots='{
"test-resources.<NAMESPACE-WITH-DOTS>": "./"
}'
></script>
</head>
<body>
</body>
</html>

```

### The UI5 Test Suite Module

The test suite module represents the configuration file for the UI5 test suite. The module must return a configuration object in the following basic structure:

- The `name` property represents the name of the test suite and is displayed in the test suite overview page as title.

- The `defaults` object contains the default [Configuration Options](configuration-options-738ed02.md) for tests.

- The `tests` object contains the definition and configuration for the individual test modules. Configuration of the individual test modules can override the default configuration. For more information on how to add a defined test module to an existing test suite, see [Creating a QUnit Test](creating-a-qunit-test-7080029.md).

```
sap.ui.define(() => {
"use strict";

return {
name: "QUnit test suite for NAMESPACE",
defaults: {},
tests: {}
};
});
```


Here is an example of a test suite module that provides default configuration for third-party modules QUnit and `sinon`. We recommend setting the version manually to prevent test failures when SAPUI5 upgrades a third-party module to a new major version with breaking changes. By default, the latest available versions are used.

It also provides [Configuration of the SAPUI5 Runtime](configuration-of-the-sapui5-runtime-91f08de.md) at `ui5` to set the theme to `sap_horizon`. The `loader.paths` configuration is used to map the project-specific namespace to the correct location. Unlike the `data-sap-ui-resource-roots` configuration in the test suite page which only registers the`test-resources` namespace, this configuration maps the productive namespace to the parent folder \(assuming the test suite is placed within `webapp/fitest`\). The generic test `page` mentioned in the next section uses query parameters to run individual tests. The placeholders `{suite}` and `{name}` are replaced with the suite and test names, respectively.

```

sap.ui.define(function () {
"use strict";

return {
name: "QUnit test suite for NAMESPACE",
defaults: {
page: "ui5://test-resources/<NAMESPACE>/Test.qunit.html?testsuite={suite}&test={name}",
qunit: {
version: 2,
},
sinon: {
version: 4,
},
ui5: {
theme: "sap_horizon",
},
loader: {
paths: {
"<NAMESPACE>": "../",
},
},
},
tests: {},
};
});
```

The `tests` object is empty for now. For more information on how to add a defined test module to an existing test suite, see [Adding a QUnit Test Module to a Test Suite](creating-a-qunit-test-7080029.md#loio708002929ea548fd9433954a9275eb5f__section_hp4_xhn_vcc).

## The Generic Test Page

The generic test page is used to run individual tests. Typically, this file is named `Test.qunit.html`.

It includes the `sap/ui/test/starter/runTest.js` script which is responsible for loading the test suite configuration and starting the test. In the test suite module, the page is configured as `page`. It receives test suite and test name through query parameters to run a test.

Unlike the UI5 bootstrap, the generic test page only accepts the `data-sap-ui-resource-roots` configuration where project-specific namespaces should be registered. All other UI5 configuration must be provided in the test suite module as described above \(`ui5` property\).

```

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<script
src="../resources/sap/ui/test/starter/runTest.js"
data-sap-ui-resource-roots='{
"test-resources.<NAMESPACE-WITH-DOTS>": "./"
}'
></script>
</head>
<body class="sapUiBody">
<div id="qunit"></div>
<div id="qunit-fixture"></div>
</body>
</html>
```
173 changes: 173 additions & 0 deletions resources/docs/1.136.7/738ed025b36e484fa99046d0f80552fd.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,173 @@
# Configuration Options

The UI5 test suite module contains the configuration for the UI5 test suite.

## **Available Options and Default Values**

The following options are available on the `defaults` and the individual test configuration objects:

> ### Note:
> The values used in the following code are the default values and are used as a fallback for options that are not defined in the configuration file - neither in the `defaults` object, nor in an individual test configuration object.

```

{
/*
* ID(s) of the module(s) to load.
*
* Can either be a single string or an array of strings.
* Each string might start with a leading "./"
* when the test module is located in the same folder
* as the testsuite configuration.
* You can use the following placeholder:
* {name} - name of the current test module
*/
module: "./{name}.qunit",


/*
* URL of the test page to start for this test.
*
* By default, all tests use the generic starter page which reads the suite
* configuration, finds the tests and starts the configured test components
* before it requires and executes the configured test module(s).
*
* The URL must be relative to the application root and can use the following
* placeholders, enclosed in curly braces:
* {suite} - name of the testsuite (configuration)
* {name} - name of the current test module
*/
page: "resources/sap/ui/test/starter/Test.qunit.html?testsuite={suite}&test={name}",


/*
* Title of the test.
* The URL must be relative to the application root and can use the following
* placeholders, enclosed in curly braces:
* {suite} - name of the testsuite (configuration)
* {name} - name of the current test module
*/
title: "QUnit tests '{name}' of suite '{suite}'",


/*
* QUnit configuration.
*
* Either can be a null or false or an object with the properties documented below.
* The values null and false are equivalent to the object { version: null }
*/
qunit: {
/*
* Version of QUnit that should be loaded.
* If set to a null, QUnit won't be loaded.
* If set to "edge", the newest available version of QUnit will be used.
* If set to a number, the corresponding version of QUnit will be used if supported.
* Currently supported versions are 1 and 2, an error will be thrown for unsupported versions.
*/
version: "edge",

/*
* Most statically configurable options from QUnit.config can be configured,
* e.g. reorder, blocking etc.
* Note that 'autostart' is an exception. To avoid timing issues with asynchronous test
* loading, 'autostart' will always be set to false. Only after all tests have been loaded,
* QUnit.start() will be called, either by the generic test starter or by the test module itself,
* see the general test option 'autostart' below.
*/
// reorder: true // only serves as an example, not part of the internal defaults of the starter
},

/*
* Sinon.JS configuration.
*
* Either can be a null or false or an object with the properties documented below.
* The values null and false are equivalent to the object { version: null }
*/
sinon: {

/*
* Version of Sinon.JS that should be loaded.
* If set to null, Sinon won't be loaded.
* If set to "edge", the newest available version of Sinon will be used.
* If set to a number, the corresponding version of Sinon will be used if supported.
* Currently supported are versions 1 and 4, an error will be thrown for unsupported versions.
*/
version: "edge",

/*
* Whether one of the sinon-qunit bridges will be loaded.
* When set to true, the sap/ui/thirdparty/sinon-qunit bridge will be loaded for Sinon 1
* and the sap/ui/qunit/sinon-qunit-bridge will be loaded for newer versions of Sinon.
*
* The bridge will only be loaded after both, QUnit and Sinon.JS have been loaded.
* If either QUnit or Sinon.JS are not loaded, no bridge will be loaded.
*
* If Sinon.JS is not loaded, but QUnit, the bridge will not be loaded, but a shim
* with dependencies will be configured. This allows tests to load Sinon.JS/the bridge on
* their own without taking care of the bridge dependencies.
*/
qunitBridge: true,


/*
* Any other statically configurable Sinon option can be specified as well.
* Note that they only play a role when a sandbox is used.
*/
useFakeTimers: false,
useFakeServer: false
},


/*
* Code coverage options.
* The qunit-coverage module will always be loaded after QUnit has been loaded to enable the coverage
* option. When the 'coverage' parameter is set in the URL (e.g. because the coverage checkbox has been
* clicked), then blanket will be loaded before qunit-coverage to avoid synchronous loading of it.
*/
coverage: {
only: null,
never: null,
branchTracking: false
},

/*
* UI5 runtime configuration options.
*
* All properties will be copied to window["sap-ui-config"].
* If window["sap-ui-config"] doesn't support it or if the value is of a type
* not supported for window["sap-ui-config"], executing the UI5 Core might fail.
*
* Only exception for now: the libs property can be an array of library names,
* not only a comma separated string.
*
* To ease test development, the following defaults are defined by the test starter:
*/
ui5: {
noConflict: true,
libs: [],
theme: "default"
},

/*
* UI5 Loader configuration.
*
* The provided configuration will be passed to `sap.ui.loader.config` and can be used to
* configure paths, shims, and other loader configuration.
*/
loader: {},

/*
* Whether the test starter should call QUnit.start() after all prerequisites have been fulfilled
* (e.g. QUnit, Sinon, a bridge, have been loaded, coverage tooling has been loaded and configured,
* the Core has been booted, the test modules have been loaded and executed).
*/
autostart: true,


/*
* Whether the test starter should skip a test file. Such tests will remain in the overview list,
* but won't be executed in the test suite.
*/
skip: false
};
```
Loading