When creating a snippet for a browser or mobile test, the Snippet Editor starts with a predefined mablJavaScriptStep
function. Understanding how to write your code within this predefined function is an important first step to implementing custom JavaScript in your tests.
This article describes the components of the Snippet Editor for browser and mobile tests, including examples to illustrate how they work:
- The mablJavaScriptStep function
- Parameters
- The mablInputs object
- The callback
- Save options
- Version dropdown
GenAI Script Generation
If you're new to writing snippets or just need help getting started, try describing what you want to do in the AI Snippet Generator. Enter your prompt into the input field and click Generate to create a new snippet or modify an existing snippet.
See the article on GenAI Script Generation for more information.
The mablJavaScriptStep function
Every snippet consists of a predefined function called mablJavaScriptStep
. Your code goes within this function.
External libraries
Importing external JavaScript libraries is currently not supported.
For example, the following snippet takes the value of the variable string
, converts it to lowercase, and passes the output to the callback
function:
function mablJavaScriptStep(mablInputs, callback) {
string = 'SAMPLE'
const result = string.toLowerCase();
callback(result);
}
By default, the mablJavaScriptStep
function has two parameters: mablInputs and callback. If you want to pass in different input values for your snippet, you can also add custom parameters.
Parameters
To make a snippet more reusable in different contexts, add custom parameters to the left of the code editor:
The parameters section in the Snippet Editor
As an example, for a snippet that converts text to lowercase, you can add a parameter for the string that you want to convert to lowercase:
function mablJavaScriptStep(mablInputs, callback, string = `SAMPLE`) {
const result = string.toLowerCase();
callback(result);
}
To reuse the snippet in a different context, override the default value of the parameter string
:
Overriding a default parameter value
The Snippet Editor always passes parameter values as strings. For example, if you have a JSON response body returned from an API step and you pass it in as a parameter, it will become a string instead of an object.
When a parameterized snippet is inside a flow, any updates to the snippet parameter values automatically apply to all instances of the flow. If you want to scope parameter values locally to each instance of a flow, create flow parameters instead and use them as the snippet parameter values.
Referencing variables in parameters
Parameters also support mabl variable syntax, so you can reference values that change depending on the context.
For example, if you extracted a last name from the page and stored it in the variable last_name
, you could update the default value of the parameter string
to reference the variable using mabl variable syntax: {{@last_name}}
:
function mablJavaScriptStep(mablInputs, callback, string = `{{@last_name}}`) {
if (string === undefined) {
throw "parameter 'string1' was not defined"
}
const result = string.toLowerCase();
callback(result);
}
For reusable snippets, if you save a variable as a default parameter value, make sure to add conditional logic to throw an error message if the variable isn't defined.
When you type {{@
in the input field for the default value, a dropdown appears with a list of variables that are currently available in the test. For more information on variables available in your test, see the article on types of variables.
mablInputs
mablInputs
is a read-only object containing variables available in the test. Previously, snippets did not support parameters, and the mablInputs
object was the only way to access variables from the test.
Here are some examples of variables that you can access through the mablInputs object:
- Any user-created variable:
mablInputs.variables.user.your_variable_name
- The loop index:
mablInputs.variables.web.runtime.flow_run_ordinal_index
- The test run ID:
mablInputs.variables.web.test_run_id
Unlike parameter values, which are always converted to strings, variable values accessed through mablInputs
retain their original type. For example, if a variable's value is the response body from an API call, the variable will still be an object.
Callback
The callback function completes the snippet step. The value that the callback returns is rendered as output for the snippet step. After the callback runs, mabl proceeds to the next step in the test.
Maximum run time for a JavaScript snippet
Test execution will wait up to five minutes for the callback before failing. Be sure to call this after the completion of any asynchronous code that needs to execute.
Supported types of return to the snippet include:
- Booleans
- Strings
- Numbers
- Objects
If the callback function doesn't run or doesn't return a value, the snippet step will fail.
Asynchronous operations
Although the mablJavaScriptStep
function requires a callback value to complete the step, it also supports other asynchronous operations, including async
/await
and promises.
Async/await and promises
Functions declared with async
return a promise, and await
pauses the execution of the function until the promise resolves.
For example, the following JavaScript snippet sets the geolocation for a mobile device with asynchronous functions. It makes an asynchronous call to callAppium()
to access the Appium driver object and set the geolocation, and then it uses promises to return the result:
function mablJavaScriptStep(mablInputs, callback, altitude = "10", latitude = "48.85873;", longitude = "2.29373") {
async function callAppium() {
const driver = await mabl.mobile.getDriver();
await driver.setGeoLocation({ latitude, longitude, altitude });
return "Geo Location set: " + latitude + ", " + longitude + ", " + altitude;
}
callAppium()
.then((result) => callback(result))
.catch((error) => callback(error));
}
Save options
Click on the down arrow next to the Save button to see the full range of save options:
Save
The default option for existing snippets.
Save as one-time snippet
Saving as a one-time snippet can be useful if you have no plans of reusing the snippet. If you change your mind later, however, you can always convert a one-time snippet into a reusable snippet by clicking "Save as new reusable snippet."
One-time snippets do not appear on the snippets page and are versioned like any other test step.
Save as new reusable snippet
If you need to use the same JavaScript step in multiple tests or several times in the same test, save it as a reusable snippet. If the JavaScript needs to be updated later, you can update it in one place. All tests that contain the snippet will use the updated version.
Snippets and branching
Reusable snippets do not adhere to branching. Any changes made to a reusable snippet will synchronize across all usages of it. To manage a snippet on a branch, save it as a one-time snippet and put it in a reusable flow.
All snippets that appear on the snippets page - Tests > Snippets - are reusable snippets. When working with snippets from the snippets page, keep in mind the following:
- New snippets are always saved as reusable snippets.
- While existing snippets can be updated, you cannot create a new snippet from an existing snippet outside of the mabl Trainer.
- If you want to check the results of a snippet for a browser or mobile test, you need to open the snippet in the mabl Trainer.
Version dropdown
Every time you save changes to a snippet, mabl creates a new version. Use the version dropdown to track changes to snippets and restore older versions.
Accessing older versions of a snippet
Snippet change history is only accessible for snippets edited from the snippets page: Tests > Snippets.
Although saving a snippet from within the mabl Trainer does create a new snippet version, the Snippet Editor in the mabl Trainer does not include a version dropdown.