Print

How to automate your tests

The quick drawer is your tool to create your test cases, page actions or step definitions. It holds every action that JOSF can execute, including your own page actions, API requests and data storages. This enables you to drag your steps and page actions into your test case or to structure it by adding groups.

Test steps

From the test steps view, you can drag in new groups to structure your test case or to influence the test flow with conditional groups.

Predefined actions

In this section, all the stock and custom actions are shown in the action speed-dial. By default, the Web browser actions are active, but you can switch to the API verifications via the select box.

All these actions can be dragged into your test at any point. Each action will have sub actions and options to configure them to your situation, but are configured to accommodate most use-cases.

User defined actions

In here, you can navigate through your own created Pages, APIs and Data storages to view and add these to your test.

Simply open any of the items and drag them into your test!

Copied steps and groups

If you have copied a step or a group, another option will show up between the predefined actions and the user defined actions called Copied item from where you can drag the item into your test.

Test objects

The second part of the quick drawer, focusses more around objects. These could be objects that are scanned via the Page Scanner, or previously stored objects via the Page Objects tab.

Page scanner

The page scanner is capable of scanning the current web browser, opened by JOSF. You can filter on object types like Clickables, Writables or Readables or toggle on the advances mode and filter on specific HTML elements.

Each Scan result will preview the found object, and presents the possible location strategies, accompanied by the number of found elements when using that strategy (lower is better). Press the eye-icon to highlight the element using that strategy.

You can drag each strategy and place them in your test either as a new step, or on top of a step to apply the strategy. When placing a strategy as a new step, JOSF will prompt you what to do with it by showing the action speed-dial.

Predefined actions

There are two predefined action packs available out-of-the-box with JOSF. The Web browser- and the API call actions. Predefined actions contain sub actions and can be configured with options. For example; the Keyboard action has a type text sub action and by selecting the gearbox, you can select some extra options like clearing the field before typing or setting an interval between keystrokes.

Next to the action, sub action and options, each action also has an Object and a Data field. Most of the times the Object field contains a location strategy to select an object in the web browser and the Data field holds the data that is required. In the example above, the Object has the name=my-text locator while the Data holds the Hello World text. In this action’s case, this means that JOSF will type the text Hello World in the object found by that locator.

Note that with some actions, the object and data field are used differently. Make sure you read about an action to understand how it works!

Web browser

Click on one of the actions to navigate to the action for its documentation.

With the cookie action, you can create and delete cookies in your browser.

Note that with some actions, the object and data field are used differently. Make sure you read about an action to understand how it works!

Create a single cookie

A cookie always has a name and a value to be placed in the object field, separated by an equals-sign (=). Next to that it has options, which can be placed in the data field, comma separated.

Configuration

n/a – this sub action has no extra configuration

Delete a single

Delete a single cookie by the given name, placed in the Object field and filterable options, placed in the Data field.

In the example below, the cookie name language will be deleted, but only the one whose path equals the /admin value.

Configuration

n/a – this sub action has no extra configuration

Deletes all cookies

Delete all cookies in the current browser session.

Configuration

n/a – this sub action has no extra configuration

Keyboard

The keyboard action simulates text input into writable objects. Set an object locator in the Object field and place the data to type in the Data field.

Types text in writable objects

A cookie always has a name and a value to be placed in the object field, separated by an equals-sign (=). Next to that it has options, which can be placed in the data field, comma separated.

Configuration

  • Clear field: on / off
  • Interval between keystrokes: number of milliseconds

Press a special key like Tab or Enter

Set the special key in the Data field. Enter multiple special keys by separating them with a space.

In the example below, the Tab key is pressed twice, before the Enter key is pressed.

It is a good practice to combine multiple special keys with an interval via the action’s options.

  • ADD
  • ALT
  • ARROW_DOWN
  • ARROW_LEFT
  • ARROW_RIGHT
  • ARROW_UP
  • BACK_SPACE
  • CANCEL
  • CLEAR
  • COMMAND
  • CONTROL
  • DECIMAL
  • DELETE
  • DIVIDE
  • DOWN
  • END
  • ENTER
  • EQUALS
  • ESCAPE
  • F1
  • F2
  • F3
  • F4
  • F5
  • F6
  • F7
  • F8
  • F9
  • F10
  • F11
  • F12
  • HELP
  • HOME
  • INSERT
  • LEFT
  • META
  • MULTIPLY
  • NULL
  • NUMPAD0
  • NUMPAD1
  • NUMPAD2
  • NUMPAD3
  • NUMPAD4
  • NUMPAD5
  • NUMPAD6
  • NUMPAD7
  • NUMPAD8
  • NUMPAD9
  • PAGE_DOWN
  • PAGE_UP
  • PAUSE
  • RETURN
  • RIGHT
  • SEMICOLON
  • SEPARATOR
  • SHIFT
  • SPACE
  • SUBTRACT
  • TAB
  • UP
  • ZENKAKU_HANKAKU

Configuration

  • Clear field: on / off
  • Interval between keystrokes: number of milliseconds

Submits a form

The locator for the object might be the form or any of its elements within that form. In the example below, a first name field will be used to perform the submit on.

This action will raise an error when the located element is not (inside of) a form block.

Configuration

n/a

Local storage

Local storage allows manipulation of the browser’s local storage data.

Note that after you’ve deleted a local storage item, you might need to refresh the page for the effects to take place.

Delete a single local storage item

Provide the local storage item name in the Data field.

Configuration

n/a – this sub action has no extra configuration

Deletes all local storage items

This deletes all local storage from the current browser session. No data or object needs to be provided and the Object and Data fields can be left blank.

Configuration

n/a – this sub action has no extra configuration

Mouse

The mouse action simulates everything a user could do with a mouse.

Simulates a (left) mouse click

Configuration

n/a – this sub action has no extra configuration

Select (or toggle) specific object types

This sub action works only on checkboxes, dropdown lists or radiobuttons so make sure the locator in the Object field results in any of those elements.

If the located object isn’t any of the required object types, JOSF will raise an error telling so.

Configuration

  • Check on current state – on / off
    By turning this on, JOSF will raise a warning whenever the desired option is already selected beforehand.

Dropdown lists

When using this sub action on a dropdown list, provide the desired option in the Data field.

Checkboxes & Radiobuttons

When using this action on a checkbox, provide the desired state in the Data field.

  • To turn it on, use one of;
    • on
    • true
    • 1
  • To turn it off, use one of;
    • off
    • false
    • 0

Double clicks on a specified object

Executes a double click on the given object.

Note that using the Click action twice is different behavior that the Double click.

Configuration

n/a – this sub action has no extra configuration

Moves the mouse over the object

This moves the mouse over the given Object and hovers over it.

Configuration

n/a – this sub action has no extra configuration

Drags an object to a specified position

Drags an object (provided in the Object field) and drops it to either another object or an offset.

Configuration

n/a – this sub action has no extra configuration

To drag an object to another object, provide the drop locator in the Data field

To drag an object to an offset, for example 10 pixels down and 200 pixels to the right, provide the offset in the Data field.

The offset moves the object as many pixels as given, relative from its current position. To move the object upwards or to the left, use negative numbers. To move it downwards or to the right, use positive numbers.

Simulates a right click on the given object

Configuration

n/a – this sub action has no extra configuration

Highlights the given object

This sub action briefly changes the background color of a given object. By default the color yellow will be set as its background for a duration of 200 milliseconds.

Note that JOSF will try and reset the background color as it was before the execution of this action, but in rare cases it is possible that this color-reset does not work properly.

Configuration

Set variable

Set variables directly or based on an object found in the browser.

Directly set a given variable to a set value

To directly set a variable, enter a name-value pair (equal-sign separated) in the Data field.

Keep the Object field empty, otherwise JOSF will extract the text from that object (see next sections).

In this example, we set a variable named First name with the value JOSF ${random()}. As shown, using functions is a valid situation. For more information about functions, visit the Functions section of the documentation.

Configuration

n/a – this sub action has no extra configuration

Sets a variable to the data inside the given object

To extract the exact text from an object and store it in a variable, set the given locator to the Object field and the name of the variable to the Data field.

Configuration

n/a – this sub action has no extra configuration

In the following example, the text found in the object located by name=last-name will be set in the last name variable.

Note that we recommend to use lower-case variable names, as these are case-sensitive, meaning that using the previous example as ${Last name} will result in an empty value.

Using variables

To use a variable, use the variable-syntax combined with the variable name. For instance, if you have a variable set and named it first name, then you can use this in any Object or Data field in any of the next steps by using ${first name}.

Note that;

  • unknown variables are treated like empty values
  • variable names are case-sensitive
  • multiple variables are allowed in any of JOSF’s input fields. For example; ${first name} ${last name}
  • It’s not recommended to use parentheses in the name of a variable, as it will then be treated as a function that might not exist.

Verify

All available verification actions reside in the Verify action. All of these sub actions will either result into a PASS or a FAIL when executing the verification. If a FAIL occurs, an expected and actual comparison will be shown in the step message.

Verifies the given Data to the object’s text

This verification work with Expected and Actual data. The expected data is provided in the Data field in your step, but the actual value is extracted from the given Object.

Configuration

  • Is not: on / off
  • Contains: on / off

Given the data in the object located by the name=price strategy is: “The total amount is € 20,95”. To make this verification PASS, you must enable the Contains option, otherwise it will verify the entire text against your given expectation.

If you expect the given data to be not present, toggle on the Is not option in the options for this step.

Verifies whether an object is present (or not)

To verify the presences or absence of an object, use this sub action.

Leave the Data field blank, as it is not used with this sub action.

Configuration

  • Not present: on / off

In below example, there is a verification of the absence of the login-button.

Verify input field state

To verify whether an object is enabled or disabled, or editable or non-editable, use this action.

This can be applied to most form-objects like input fields, dropdown selections, checkboxes, radiobuttons and buttons.

Configuration

  • Is not: on / off

In below example, the object first-name is verified to be editable.

Verifies the number of objects

To verify the number of found objects by the given Object location strategy, use this action.

Configuration

  • At most: on / off
  • At least: on / off
  • Is not: on / off

By default, the At most and At least options are selected to verify an exact count, which is in this case 3.

Verify an object’s attribute

Most of the objects in a web browser contain attributes. For example, a password input field is an HTML element with a attribute names “type” with the value set to “password”. There are many attributes and value possibilities, so make sure the correct one is verified.

Configuration

  • Is not: on / off
  • Contains: on / off

The example below demonstrates the validation on the object found by the name=secret object, where the attribute “type” must equal to the value “password”.

Given the following (HTML) object definition;

<input type="password" name="secret" />

The validation step looks like this.

Verify alert contents

This sub action requires that there is an alert present in the web browser. If not, JOSF will raise an error.

Leave the Object field blank and provide the expected value in the Data field.

Configuration

  • Is not: on / off
  • Contains: on / off

Given a situation like the following; a JavaScript alert pops up.

The following step returns PASS as it’s an exact match on the actual data inside of the alert.

Verify the value or the presence of a cookie

By default, this sub action only verifies the presence of a cookie, looking for it by the name, given in the Data field.

Leave the Object field blank, as the name of the cookie, is provided in the Data field.

Configuration

  • Verify presence only: on / off
  • Is not: on / off
  • Contains: on / off

Verify presence

Verify value

To verify not only the presence, but also the value of the cookie, de-select the option Verify presence only and provide the expected value, separated with the name by the equals-sign (=).

In the below case, this results in a PASS, even when the value of the cookie named language is equal to en_US, because the Contains option is selected.

Verify the value of the current URL

The URL is part of a section of the browser, where the Verify text and value cannot reach. For that reason, this sub action is necessary.

Configuration

  • Is not: on / off
  • Contains: on / off

Given this website, where the URL is https://www.josf.nl/josf-docs/. Note how this browser (Chrome) hides the https://www. part for abbreviation.

To verify a part of this URL, the following step can be used. Note how the Contains option is selected to verify only a part of the current URL.

Verify the value of the current Tab title

The title of a tab is part of a section of the browser, where the Verify text and value cannot reach. For that reason, this sub action is necessary.

Configuration

  • Is not: on / off
  • Contains: on / off

Given this website, where the title in the active tab is JOSF Docs - JOSF.

To verify a part of this title, the following step can be used. Note how the Contains option is selected to verify only a part of the current title.

Verify a previously set variable value to an expected value

Set the actual value to the Object field (e.g. by a earlier Set variable) and an expected value in the Data field to verify the equality of numbers or text.

Tip: Use this sub action as a comparator for the Conditional group, to conditionally execute it.

Configuration

  • Is not: on / off

Verify a previously set variable value to an expected value

Set the actual value to the Object field (e.g. by a earlier Set variable) and an expected value in the Data field to verify the if the actual data contains the expected.

Tip: Use this sub action as a comparator for the Conditional group, to conditionally execute it.

Configuration

  • Does not: on / off

In the example below, the step result would be set to PASS when the ${price sentence} is “it costs € 20,95 to be precise”.

Verify a previously set variable value to an expected value

Set the actual value to the Object field (e.g. by a earlier Set variable) and an expected value in the Data field to verify the if the actual number is greater than the expected.

Note that for comparing floating numbers (e.g. 50.95) you require a period-separated number, in stead of a comma-separated number.

Tip: Use this sub action as a comparator for the Conditional group, to conditionally execute it.

Configuration

n/a – this sub action has no extra configuration

In the example below, the ${price} is set to 45 and the result for this is PASS, because 50 is greater than 45.

Verify a previously set variable value to an expected value

Set the actual value to the Object field (e.g. by a earlier Set variable) and an expected value in the Data field to verify the if the actual number is greater than or equal to the expected.

Note that for comparing floating numbers (e.g. 50.95) you require a period-separated number, in stead of a comma-separated number.

Tip: Use this sub action as a comparator for the Conditional group, to conditionally execute it.

Configuration

n/a – this sub action has no extra configuration

In the example below, the ${price} is set to 50 and the result for this is PASS, because 50 is equal to 50.

Verify a previously set variable value to an expected value

Set the actual value to the Object field (e.g. by a earlier Set variable) and an expected value in the Data field to verify the if the actual number is less than the expected.

Note that for comparing floating numbers (e.g. 50.95) you require a period-separated number, in stead of a comma-separated number.

Tip: Use this sub action as a comparator for the Conditional group, to conditionally execute it.

Configuration

n/a – this sub action has no extra configuration

In the example below, the ${price} is set to 50 and the result for this is PASS, because 45 is less than 50.

Verify a previously set variable value to an expected value

Set the actual value to the Object field (e.g. by a earlier Set variable) and an expected value in the Data field to verify the if the actual number is less than or equal to the expected.

Note that for comparing floating numbers (e.g. 50.95) you require a period-separated number, in stead of a comma-separated number.

Tip: Use this sub action as a comparator for the Conditional group, to conditionally execute it.

Configuration

n/a – this sub action has no extra configuration

In the example below, the ${price} is set to 45 and the result for this is PASS, because 45 is equal to 45.

Wait

When waiting for a specific object to appear or disappear or when waiting of a specific time.

The Wait for object sub action will raise an ERROR when the object is not found.

Wait for a specified amount of milliseconds

Set the amount of milliseconds in the Data field and leave the Object field blank.

Configuration

n/a – this sub action has no extra configuration

In below example, this step will wait for 1.5 seconds (1500 milliseconds) before it completes.

Wait for a specified object to be present or absent

Use this sub action to wait for a specific object to be present or not.

Apply a specific timeout to have the step FAIL if the object is not present in this timeframe.

When applying the Contains option, add text to the Data field, so that the step will wait until that specified data is present in the object.

Configuration

  • Not present: on / off
  • Custom timeout: time in milliseconds
    When not set, the default is 10 seconds
  • Contains: on / off

An example that waits for the object located by name=title-paragraph to be present.

Web browser

With the Web browser action, you can navigate to specific URLs manipulate tabs or execute JavaScript.

To open URLs or pages within your application

This sub action accepts either a fully qualified (including the protocol) URL, or – when the base URL is set – a path within your application in the Data field.

Configuration

n/a – this sub action has no extra configuration

Using a fully qualified URL.

Using a path, while the base URL is set within the Browser preferences.

Open a second (third, fourth, etc..) tab

Use this sub action to open another tab in the current browser. Leave the Data field blank or provide a fully qualified (including the protocol) URL, or – when the base URL is set – a path within your application in the Data field.

JOSF automatically activates the newly opened tab.

Configuration

n/a – this sub action has no extra configuration

Using a fully qualified URL.

Using a path, while the base URL is set within the Browser preferences.

Activate a specified tab

Use the Data field to provide either the tab’s title or its order number (starting from 1).

Configuration

n/a – this sub action has no extra configuration

Using the tab’s title

Using the tab’s order number, given there are 4 tabs open and we need to open the second to last tab.

Close the active tab or browser

This action closes the current active tab or, when there is only one tab present, closes the browser.

Leave the Object and Data field empty, as they are not used for this sub action.

Configuration

n/a – this sub action has no extra configuration

Resize or maximize the browser window

Provide a width x height resolution to the Data field.

Note that when using the Maximize option, it will follow the current screen resolution. This means that on different computers, different resolutions will be used.

This could lead to unexpected behavior, when executing your tests in a (headless) CI/CD pipeline, as the resolution of the execution environment are indeterminate.

Configuration

  • Maximize: on / off
    • When active, this will override the provided resolution

The provided resolution is a width of 1600 pixels by a height of 900 pixels.

You could also only set the width, by providing single number. In this example, the height will not be changed.

Refresh the current page

Leave the Object and Data field empty, as they are not used for this sub action.

Configuration

n/a – this sub action has no extra configuration

Upload a file in your browser

This sub action exists to accommodate the file upload feature in browsers.

If the file uploader is hidden (by styling/theming), this sub action makes sure the file uploader is shown. After the file selection is complete, the file uploader will be hidden again.

Make sure the Object field is set to an location strategy that leads to a file upload HTML element, which is an input object, with the attribute type set to file.

<input type="file" />

Set the Data field to a File type, to select a file from your File Explorer.

Configuration

n/a – this sub action has no extra configuration

Note how in below example the Data field type is set to a file.

Executes JavaScript in the web browser

To make use of the power of JavaScript, this sub action is able to execute that, and store any result into a variable for later use.

Executing JavaScript is an advanced function and requires some basic knowledge of this front-end scripting language.

For more advanced usage, you can use a provided Object in the JavaScript code by setting the Object with a location strategy and using the arguments[0] to manipulate that object.

Set the Data field to the Code type, to get a better view for JavaScript.

Configuration

n/a – this sub action has no extra configuration

It is important to have the syntax correct, for this action to execute correctly, like so:

variable to set = {
  // the JavaScript to execute with a return statement
    const a = 90;
    const b = 10;
    return a + b; 
}

Note how the const keyword can be used, as the script you provide is like a JavaScript function.

In below example, we use JavaScript to perform a simple calculation and store its result in the my calculation variable for later use.

For more advanced usage, you can provide an object and use that in the script with arguments[0]. In this example, the text in the login button is set to the loginText variable.

You can read more about JavaScript in its official documentation, provided by Mozilla.

Alerts

When a JavaScript alert opens in the web browser, this action allows you to handle it. An alert is triggered by a JavaScript event and exists outside of the HTML structure of the web page.

Close by accepting alert

This triggers the OK button to be pressed in the JavaScript alert.

Keep the Object and Data field empty, as they are not used for this sub action.

Configuration

n/a – this sub action has no extra configuration

Close by cancelling alert

This triggers the CANCEL button to be pressed in the JavaScript alert.

Keep the Object and Data field empty, as they are not used for this sub action.

Configuration

n/a – this sub action has no extra configuration

Store the alert text into a variable

To extract and store the alert text for later use, set the name of the variable in the Data field.

Configuration

n/a – this sub action has no extra configuration

Given this alert:

In the following example, the alert text will contain the “Hello world!”.

Type text in the alert prompt

Set the Data field to the text you’d like to type. JOSF will automatically press the OK button after typing.

Configuration

n/a – this sub action has no extra configuration

The below example will type My name is JOSF in the alert prompt.

Authenticate on HTTP level

Some domains require a username and password to be able to connect, and present a authentication popup.

Use this action before visiting the page where the authentication alert shows, to register the authentication for that website.

Note that this action only works on the chromium-based browsers like Chrome and Edge.

Configuration

n/a – this sub action has no extra configuration

The username and password should be entered in the Data field and separated by a colon (:). In the example below, the username is set to JOSF and the password is set to secret-password. E.g. JOSF:secret-password.

In this document