Table of Contents
About
This Karma plugin helps testing your UI5 projects.
Please refer to the Testing section in the UI5 Developer Guide for information about writing tests for your project.
Note: This project has been renamed from karma-openui5
to karma-ui5
with the v1.0.0 release.
For upgrade information, see the Migration Guide.
For the karma-openui5
documentation, see 0.x branch.
Quickstart
Installation
First you need to install the Karma CLI globally:
npm install -g karma-cli
You can find more information on installing Karma here.
Next, you need to add karma
and karma-ui5
as devDependencies:
npm install --save-dev karma karma-ui5
To start a browser, you also need to install a launcher, e.g. for Chrome:
npm install --save-dev karma-chrome-launcher
Configuration
To configure the plugin, you need to add two things to your karma.conf.js
:
- Specify
"ui5"
in the list of frameworks
. - Set a URL for serving the UI5 resources.
This is an example karma.conf.js
file that is sufficient for most projects:
module.exports = function(config) {
config.set({
frameworks: ["ui5"],
ui5: {
url: "https://openui5.hana.ondemand.com"
},
browsers: ["Chrome"]
});
};
Script Mode
(Optional, next step: Execution)
The configuration above implies to use the html
mode, which is recommended.
It runs your existing test pages and does not require additional Karma plugins or configuration.
However the script
mode is more flexible and better allows integration with other karma plugins / frameworks.
The following steps describe a minimal configuration for the script
mode.
With the script
mode you need to also include a testing framework and its Karma adapter, like QUnit and karma-qunit.
npm install --save-dev qunit karma-qunit
To use test spies, stubs and mocks you need to install Sinon.JS and karma-sinon.
npm install --save-dev sinon karma-sinon
Both frameworks need to be added to the karma.conf.js
.
Note that ui5
should be the first entry.
frameworks: ["ui5", "qunit", "sinon"]
Next, you need to provide the UI5 bootstrap configuration (see config).
The resourceRoots
configuration should be aligned with your project namespace.
ui5: {
config: {
async: true,
resourceRoots: {
"sap.ui.demo.todo": "./base/webapp"
}
}
}
Last but not least the test modules need to be listed, so that they are executed.
ui5: {
tests: [
"sap/ui/demo/todo/test/unit/AllTests"
]
}
Here is the full example for the script
mode:
module.exports = function(config) {
config.set({
frameworks: ["ui5", "qunit", "sinon"],
ui5: {
url: "https://openui5.hana.ondemand.com",
mode: "script",
config: {
async: true,
resourceRoots: {
"sap.ui.demo.todo": "./base/webapp"
}
},
tests: [
"sap/ui/demo/todo/test/unit/AllTests"
]
},
browsers: ["Chrome"]
});
};
Execution
With the above configuration, karma will by default run all tests in Chrome and listen for changed files to execute them again (watch mode).
karma start
For CI testing, you can run Chrome in headless mode and execute the tests only once using the singleRun
option:
module.exports = function(config) {
config.set({
browsers: ["ChromeHeadless"],
singleRun: true
});
};
The options can also be set via CLI arguments:
karma start --browsers=ChromeHeadless --singleRun=true
For more information, see the "Configuration File" documentation from Karma.
Karma Configuration Requirements
There is an important requirement for using this plugin:
- The karma
basePath
option must point to your project root, not to a subfolder like "webapp". This is the default when your karma.conf.js
is in the project root.
It is required for the type detection and automatic inclusion of your project files.
Options
All configuration options need to be defined in an ui5
object in your Karma configuration:
module.exports = function(config) {
config.set({
ui5: {
}
});
};
url
Type: string
CLI: --ui5.url
The URL where UI5 should be loaded from.
When omitted and the project contains a ui5.yaml
file, UI5 Tooling will be used as server middleware. Beware of restrictions outlined in Notes on UI5 Tooling Custom Server Middleware.
Example:
ui5: {
url: "https://openui5.hana.ondemand.com"
}
type
Type: enum
("application"
/ "library"
)
Defines the project type.
If not set, it is automatically detected based on
- the type defined in
ui5.yaml
, or - existing folders
- "webapp" =>
application
- "src" / "test" =>
library
Example:
ui5: {
type: "application"
}
paths
Type: object
Custom path mappings for project folders based on the type
.
Use this option only when the automatic type detection does not work because the project uses a different folder structure.
Example application
:
ui5: {
type: "application",
paths: {
webapp: "src/main/webapp"
}
}
Example library
:
ui5: {
type: "library",
paths: {
src: "src/main/js",
test: "src/test/js"
}
}
configPath
Type: string
Default: "ui5.yaml"
CLI: --ui5.configPath
Path to the UI5 configuration file.
It is resolved relative to the project root.
Example:
ui5: {
configPath: "ui5-test.yaml"
}
mode
Type: enum
("html"
/ "script"
)
Default: "html"
Configures the mode how tests should be executed.
html
The HTML mode runs QUnit test suites and test pages in a separate context.
It has built-in support for QUnit. The QUnit adapter must not be used in combination with this mode. Other framework plugins must also not be used. Instead, the required libraries such as sinon should be loaded within the test.
ui5: {
mode: "html"
}
Specific config options:
script
The script mode includes the UI5 bootstrap script. It allows to pass UI5 config and loads your test modules.
You need to also install and configure an adapter for your test framework such as QUnit, to enable test execution and reporting.
ui5: {
mode: "script"
}
Specific config options:
testpage
Type: string
CLI: --ui5.testpage
Specific to "html" mode
A file path pointing to a test page or test suite that should be executed.
The path needs to be relative to the project root.
If not set, the project is scanned for available test suites (testsuite.qunit.html
).
When exactly one test suite is found, it will be used as testpage
. Otherwise, all found pages are printed out and one of them needs to be configured manually.
Example:
ui5: {
mode: "html",
testpage: "webapp/test/myTestPage.qunit.html"
}
urlParameters
Type: Array
Specific to "html" mode
URL parameters to append to every testpage.
Example:
ui5: {
mode: "html",
urlParameters: [{
key: "hidepassed",
value: true
}]
}
failOnEmptyTestPage
Type: boolean
Default: false
CLI: --ui5.failOnEmptyTestPage
Specific to "html" mode
Reports an error when a test page does not define any tests.
The Karma configuration failOnEmptyTestSuite
only covers the case when no tests were defined at all, but not when just one testpage doesn't define tests.
Example:
ui5: {
mode: "html",
failOnEmptyTestPage: true
}
config
Type: object
Specific to "script" mode
Configuration of the UI5 bootstrap.
Example:
ui5: {
mode: "script",
config: {
bindingSyntax: "complex",
compatVersion: "edge",
async: true,
resourceRoots: {
"sap.ui.demo.todo": "./base/webapp"
}
}
}
tests
Type: Array
Specific to "script" mode
List of test modules that should be loaded (via sap.ui.require
).
If not provided, the test files must be included in the karma files
config to load them with <script> tags.
Example:
ui5: {
mode: "script",
tests: [
"sap/ui/demo/todo/test/unit/AllTests",
"sap/ui/demo/todo/test/integration/AllJourneys"
]
}
fileExport
Type: boolean
or object
Default: false
Configures whether report files provided by tools like UI5 Support Assistant are exported to the file system.
Optionally, an output directory can be set to specify the export path.
Example boolean
:
ui5: {
fileExport: true
}
Example object
:
ui5: {
fileExport: {
outputDir: "directory/to/export/files"
}
}
Projects can also add report files by themselves by setting or enhancing the global window._$files
array in the executed source code in the following way:
window._$files = window._$files || [];
window._$files.push({
name: "file_name.txt",
content: "file content"
});
API
helper
This plugin also comes with a helper module to be used in your Karma configuration file.
configureIframeCoverage
Enables code coverage for iframes.
Can only be used in combination with the karma-coverage plugin (v2.0.0+).
Must be called from the karma configuration function after the coverage plugin has been configured.
The config
object must be passed as a parameter.
module.exports = function(config) {
config.set({
});
require("karma-ui5/helper").configureIframeCoverage(config);
};
Notes on UI5 Tooling Custom Server Middleware
If the url-option is not used, and if the project contains a ui5.yaml
file, karma-ui5
will automatically use UI5 Tooling to start an internal server. Any custom middleware configured in the ui5.yaml
will be used automatically.
However, since Karma uses the connect
framework, as opposed to UI5 Tooling's express
, custom middleware might not always work as expected. Compared to connect
, the express
framework provides a more versatile API to middleware.
Therefore, if you plan to use custom middleware in an integrated scenario with karma-ui5
, you must restrict the middleware to using the connect
API only to ensure compatibility.
Alternatively, you can start a server with the usual ui5 serve
command and configure the corresponding URL.
For more information see UI5 Tooling - Custom UI5 Server Middleware.
Big Thanks
Cross-browser Testing Platform and Open Source <3 Provided by Sauce Labs.