Print

Start with JOSF CLI

Note that the JOSF CLI requires a valid JOSF licence.

When installing JOSF, the JOSF CLI is installed automatically. The JOSF CLI could be used locally on your machine for unattended test case execution, but is specifically useful in combination with CI/CD pipeline tooling.

The CLI is executable with these commands;

  • josf --help
  • josf --version
  • josf --verify / josf -v
  • josf --config
  • josf --run / josf -r

Each command is executed because of the double-dash. Some commands also has a short-hand single-dash version. The short-hand commands are also listed in josf --help.

Note that JOSF CLI allows for concatenated command executions. For example, josf --help --version (note the double dash) will first run the help command and then run the version command. Useful for performing multiple configurations and executing a run directly afterwards.

josf –help / josf -h

When in doubt, call the –help command. Running this will show the global help. To get help on a specific topic, run the –help command with the topic as the second argument, e.g;

  • josf --help run
    This will show the help page of the run command.
  • josf --help config
    This will show the help page of the config command.

josf –version

Prints the version number of JOSF core and the JOSF CLI

josf –verify / josf -v

Verifies if JOSF CLI is ready to run. This command tests the following prerequisites for a test run;

  • Checking connection with JOSF
  • Checking compatibility
  • Checking licence
  • Checking Selenium Server is up and running
  • Checking headless Chrome instance

JOSF requires to be started, since the test runs are executed against that JOSF instance. Next to that, JOSF CLI and your JOSF instance need to be compatible and you require a valid licence to run JOSF CLI.

Selenium server

Even though your tests might not require any web browsers, for example when you explicitly run API tests, but still JOSF requires a Selenium Server to be up and running. Since JOSF 2.8, the Selenium server is built into JOSF and requires no additional start-up of any kind. However, your JOSF does require a correctly configured headless Chrome instance.

Headless Chrome instance

Since JOSF 2.7, the correct Headless Chrome instance configuration is set-up for you, to run JOSF CLI. But maybe you’ve lost the configuration, or you’ve installed JOSF manually. In that case, JOSF CLI presents the required configuration to you. This is a JSON snippet, which needs to be added to the driver configuration file.

For now, there is no interface or form to update the Headless Chrome instance correctly, so this needs to be manually added to the driver-list.json file found in the JOSF/testcases/settings directory.

{
    "displayName" : "Headless Chrome",
    "hubUri" : "http://localhost:4444/wd/hub",
    "browserName" : "chrome",
    "capabilities" : { },
    "arguments" : [ "--headless" ]
}

The most important part is the “displayName” and “arguments” parts. Do not change any of these settings as JOSF CLI depend on these values.

josf –config

The default configuration of the JOSF CLI will work for you most of the time. If you need to change any of the default configuration, execute; josf --config <item> <value>. For example, to change the log-level, execute;

josf --config log-level debug

Configuration options

ItemDefault settingDescription
josf-base-urlhttp://localhost:8090The location of the JOSF core API
josf-app-urlhttp://localhost:8090The location of the JOSF app
selenium-serverhttp://localhost:4444The location of the selenium server
log-levelinfoThe log level. All possible options are; all
debug info warn error fatal trace off
Note that when using the --config command, any change in configuration is stored in the folder where the josf --config is executed, not where JOSF installed.

josf –run / josf -r

The run command is able to execute a playbook. This is particularly useful for unattended or headless execution of your tests, mostly used in CI/CD pipeline tooling. Next to that, the playbook option accepts the environment and browser option to be changed, during the execution of the playbook.

Playbook

The playbook option accepts either the ID or the name of the playbook as a parameter. It could happen, that your playbook has some special characters in them, like an ampersand (&) or quotes (‘,  “, `), that even though are allowed in JOSF, might not be supported by your command line interface to be processed correctly. We therefore always recommend avoiding using those characters.

We recommend when passing the playbook name, to use single-quotes (‘) or double-quotes (“), or back-ticks (`) around the playbook name.

As a work-around, the playbook option also accepts the playbook ID, as a parameter. The ID can be found when opening the playbook in JOSF. In the playbook editing screen, find the bread-crumb path in the top and copy the last part. This ID is also found in the URL path of the editor.

josf --run playbook 'my playbook'

josf --run playbook 'v210v63gv2'

Next to that, the options environment and browser can be passed either individually or together.

project / projectPath

From JOSF 2.13 onwards, JOSF works with projects. This means, that when you run a playbook, the CLI runner requires you to add the project or projectPath option. When you omit this value, JOSF CLI will use the first project present in the workspace file’s project list. If there is no workspace file, a new workspace file will be created on JOSF startup, and when there is a testcases folder present, JOSF will automatically add this path as the first project. In short: omitting the project of projectPath option, selects the project that resides in the /testcases folder (if present).

josf --run playbook 'my playbook' project 'my project'

josf --run playbook 'my playbook' projectPath 'c:\path\to\testcases'

Environment -optional value

When omitting this option, JOSF takes the current activated environment from JOSF. If you’ve configured any environments within JOSF, you can change the used environment by passing the environment option. Given, you have configured two environments named ‘development environment’ and ‘test environment’ and by default, the ‘test environment’ is active. Passing the environment option with value ‘development environment’, would temporarily activate that configured environment, until the run command is completed. It will then reset the configuration back to the original value.

josf --run playbook 'my playbook' environment 'development environment'

Note that this setting will configure JOSF to activate that environment. That means that when running a playbook like this, if you open JOSF, it will be configured with the temporarily activated environment.

Browser -optional value

When omitting this option, JOSF takes the current activated browser from the JOSF settings. By passing this option, JOSF CLI will temporarily activate the given browser to be used within JOSF.

josf --run playbook 'my playbook' browser 'Remote Firefox'

Note that this setting will configure JOSF to activate that browser. That means that when running a playbook like this, if you open JOSF, it will be configured with the temporarily activated browser.

retryCount -optional value

The retryCount option accepts a number. When a playbook run fails, all the tests within will be rerun, to a maximum of this retryCount value or untill all the tests PASS.

josf --run playbook 'my playbook' retryCount '3'

secretsPassword -optional value

If you have a password protected project and you are using the ${secret()} function, you must add this option with the actual password in the CLI command.

josf --run playbook 'my playbook' secretsPassword 'MyPassword20!'

We encourage you to use a centralized vault or environment variables to retrieve the actual password.

testTimeoutInMinutes -optional value

The testTimeoutInMinutes option accepts a number. JOSF will terminate a test when it exceeds this value and continue with the remaining tests. The default for this is set to 15 minutes and applies only to playbook runs executed via the CLI.

When terminating a test, the current executing and remaining steps will be set to an ERROR state with the message indicating the timeout has expired.

In the example below, the timeout per test will be set to 30 minutes.

josf --run playbook 'my playbook' testTimeoutInMinutes '30'

In this document