Anatomy of a Project

This guide assumes, that you have finished the “Getting started” guide or that you are experienced with Sakuli v1.

Most of the complexity and conventions come due to the backwards compatibility to V1 which requires such a folder and file layout for various reasons (the biggest is Sahi). Sakuli now offers various ways to reduce this complexity dramatically. These features will eventually come in upcoming releases.

Setup and configuration

The minimum setup of a Sakuli project looks like this:

- **your-sakuli-project** *Homefolder of the project* - **package.json** *All dependencies and setup for NodeJs* - **** *(optional: Configuration for all Testsuites)* - **testsuite-a** *Homefolder of a testsuite* - **testsuite.suite** *Defines which testcases belongs to the testsuite* - **** *Configuration for the testsuite (overrides configuration from '../')* - **testcase** *Home of the testcase* - **testcase.js** *The actual testcase*

This file layout also represents the logical structure of Sakuli which consists of a testsuite with one or more testcase(s). Sakulis run command takes a path to a testsuite folder and runs all testcases defined in testsuite.suite from the given path.


This file is a relic from Sahi where you define testcases and their respective starturls. It has a simple own format:


<CASE-PATH> is a path within the testsuite file which has to contain the file <CASE_FILE>. The <START-URL> is no longer used by Sakuli (but required to fulfil the file format). The format also supports comments (// at the beginning of a line). Comments are the usual way to activate or deactivate testcases.

The configured start-url is omitted to force test authors to write explicit navigation to the url in the testcases using _navigateTo.

Properties Files

Each testsuite requires a file with at least one entry:

It “inherits” its values from ../ (which also means, that the same property from is overridden).

Property files are a common way to store configuration in Java, the former runtime for Sakuli. It is a simple key value format (<KEY>=<VALUE>) where every line defines a key-value pair. To organize the keys, it is a common - but not required - pattern to separate names by dots (similar to Java namespaces)

There are several predefined properties to configure the behavior of Sakuli (* indicates a required property):

Property Type: Default Comment / Example String*: / Name of the Suite shown in the output and used by the forwarder
testsuite.browser String: ‘firefox’ Browser which is started by the webdriver (It can be overridden by --browser commandline argument)

You can also define own properties and use them in your testcases. Just put your custom property key with its value in one of the .property files and in your test case you are able to retrieve this value with the Environment Class:

// omitting boilerplate 
// assuming you have added 
// in one of the property files
const env = new Environment();
await _setValue(_textbox('username'), env.getProperty(''));