Skip to main content

Using Pre-Run Executables

In the real world, there's no such thing as a "stock" version of any particular browser, because users can easily modify them with add-ons, change settings, and set profiles with specific functionality. There are also situations in which browser or virtual machine configurations can cause issues with your tests. For these reasons, you may want to make changes to the browser or VM configuration before your test runs. For example, you might want to test against a security-conscious user profile that includes using private windows, blocking all pop-ups, and disabling JavaScript, or you may want to change settings that could raise dialogs and cause your tests to fail.

There are different ways to deal with these situations, depending on the type of browser you're testing against.

  • Firefox includes a Profiles feature that lets you manage everything from passwords to security settings to site-specific settings, like which sites are allowed to display pop-ups. The Selenium driver for Firefox includes a webdriver.firefox.profile system property that lets you select which profile you want to use in your testing.
  • With Chrome, there is a long list of switches that you can set to change browser behavior, which you can pass as arguments to the Chrome WebDriver.
  • Unfortunately, neither Safari or Internet Explorer have a built-in way to edit user settings, which is where pre-run executables come into play.

A pre-run executable is simply a script that you download to the Sauce Labs virtual machine and run prior to a test to change settings for Safari, Internet Explorer, or any other browser, or to configure the virtual machine that your tests will run on.

What You'll Need​

Setting Up Pre-Run Executables​

You can configure your Sauce testing jobs to use pre-run executables with the prerun capability as described in Test Configuration Options.

Pre-run executables are commonly used to change browser settings and VM configurations before a test starts. This page provides a few examples of these scripts, and covers setting prerun as a desired capability during test configuration.

Root and Administrative Permissions on Sauce Labs Virtual Machines

sudo access is not allowed on Linux/Mac virtual machines. Administrative access is not allowed on Windows VMs.

Writing a Configuration Script​

This example script disables the warning that Safari pops up when using basic HTTP authentication to access a website.

disable_fraud.sh
#!/bin/bash
defaults write com.apple.Safari WarnAboutFraudulentWebsites false
Match File Types to Your Operating System

When creating your executable file, take into account the operating system you'll use for your tests. For example, Bash commands won't work on Windows machines, which instead require a .bat or .com file.

Storing a Configuration Script​

Your script can be stored in GitHub or in App Storage (for more information see Common Error Messages). You can also use Gist to easily host your executable file. Make sure to use the link containing the raw file contents.

Set the prerun Capability​

This example sets prerun to point to myscriptstorage.com, which hosts the script disable_fraud.sh used as an example in step 1.

desired_capabilities['prerun'] = {
    'executable':'http://myscriptstorage.com/disable_fraud.sh',
    'background': 'false'
}

This example accesses the same script from App Storage:

desired_capabilities['prerun'] = {
    'executable':'storage:filename=disable_fraud.sh',
    'background': 'false'
}

Setting Up Silent Mode​

One of the arguments that can be added to the prerun capability in your test configuration options is --silent, which can be abbreviated to /S. This argument will "silently" install the executable without any modal dialogs or other installation processes showing up in your tests. Here's an example of how you would set the prerun capability to run in silent mode:

"prerun": {
    "executable": "http://url.to/your/executable.exe",
    "args": [ "/S", "-a", "-q" ],
    "background": true,
    "timeout": 120
}

Setting Basic Authentication in Safari​

In Safari, when you try to navigate to a URL that uses basic HTTP authentication, a warning dialog pops up that will derail your automated tests unless you can resolve it. You can execute a short shell script as a pre-run executable to configure Safari to not show this message.

note

You can only use this for Safari versions up to and including 10.x.

This script clears the Warn when visiting a fraudulent website option in Safari's preferences, so that your automated tests that use basic authentication over HTTP will execute without triggering the warning.

#!/bin/bash
defaults write com.apple.Safari WarnAboutFraudulentWebsites false

The disable_fraud script used in the preceding examples is hosted as a Gist on GitHub.

Downloading Files to a VM Prior to Testing​

You can use a pre-run executable script to download files from a public location to the Sauce Labs virtual machine running your tests. This topic contains example scripts for downloading remote files on different operating systems, and details configuring the prerun capability in your tests.

OS X 10.6, 10.8, 10.9, 10.10​

This shell script will fetch the file at the URL and save it to /Users/chef/file.txt.

#!/bin/bash
curl -o /Users/chef/file.txt http://mywebsite.com/file.txt

Set Prerun Capability​

After you've created the download script, use the prerun capability in your test script to point to its location.

If your script is in a publicly accessible location, you need to add the URL to the prerun capability.

capabilities['prerun'] = 'http://location.of/curl.sh'

Editing the VM's Host File​

note

Editing the Host file of the virtual machine will not work if Sauce Connect Proxy is in use because the Host file of the machine running Sauce Connect Proxy is referenced, so make the desired changes there, instead.

An example of configuring a Sauce Labs virtual machine with a pre-run executable is editing the host file in the virtual machine, so when the driver tries to access a particular domain, like google.com, it will be redirected to a new IP address, for example 162.222.75.243 (saucelabs.com). As with other prerun configurations, the basic steps are:

  1. Write a script with the URL redirect to the new IP address.
  2. Upload the script to a publicly accessible location, like GitHub or App Storage.
  3. Set the prerun capability in your test script to load the script as host file in the Sauce Labs virtual machine.

Host File Script​

Here are examples of the host file script, EditDNS, in both OS X/Linux and Windows versions.

bash OS X/Linux Host File Script​

#!/bin/bash
echo "162.222.75.243 www.google.com" >> /etc/hosts

Windows Host File Script​

@echo off
echo 162.222.75.243 www.google.com > %temp%\temphosts.txt
type C:\WINDOWS\system32\drivers\etc\hosts >> %temp%\temphosts.txt
copy /Y %temp%\temphosts.txt C:\WINDOWS\system32\drivers\etc\hosts

Creating JSON Objects for Multiple Arguments​

If your test script is written in Java, you will need to create a JSON object if you want to include multiple arguments, such as --silent, -a with the prerun capability.

The JSONObject Class/Library

Make sure your test script imports the JSONObject class/library so you can create the JSON object.

JSONObject obj = new JSONObject();
obj.put("executable","http://url.to/your/executable.exe");
LinkedList<String> list = new LinkedList<String>();
list.add("/S");
list.add("-a");
list.add("-q");
obj.put("args",list);
obj.put("background","true");
obj.put("timeout", "240");
System.out.print(obj);

If your test script is written in C#, you will need to create a Dictionary object with the prerun capability as JSON Objects do not work well with C# projects.

The C# Dictionary Object

When creating the Dictionary object, make sure the TKey is of value "string" and the TValue is of value "object"

var obj = new Dictionary<string, object>();
obj.Add("executable", "http://url.to/your/executable");
obj.Add("background", true);
obj.Add("timeout", 120);

When you set your test capabilities, refer to the object you created as the path to the executable, as in this example:

DesiredCapabilities capabilities = new DesiredCapabilities();
capabilities.setCapability("prerun", obj);

Running an AutoIt Script​

When using Sauce Connect to run local tests on a Windows machine, you may encounter an Integrated Windows Authentication (IWA) dialog, also known as NTLM or Domain authentication. This is because the machine that Sauce Connect is running on is used to look up the host where the site or app under test is located. If the host has IWA enabled, the authentication request will be passed back through Sauce Connect to the Sauce Labs browser. Because there is no registry key available on our Windows virtual machines to disable this authentication, the solution is to create an AutoIT script to respond to the dialog.

You can use the AutoIT Script editor to write and save your script.

The script for handling the IWA dialog should look like this:

WinWaitActive(“Windows Security”)
Send(“Username”)
Send(“{TAB}”)
Send(“mysupersecretpassword”)
Send(“{ENTER}”)

For Username and mysupersecretpassword, enter the authentication credentials required by the Windows host.

When you save the script, it will be an .au3 file, and you will need to compile it as an .exe file. Once compiled, you can use it as a pre-run executable with this desired capability call:

"prerun": { "executable": "http://url.to/your/executable.exe",
            "args": [ "--silent", "-a", "-q" ], "background": true }

If using Sauce Storage for your pre-run executable send the following desired capability:

"prerun": { "executable": "storage:filename=executable.exe",
            "args": [ "--silent", "-a", "-q" ], "background": true }

64 v. 32-bit Version of AutoIT​

The 64bit version of AutoIT works on IE11, and not on IE9. The 32bit version works with both browser versions.

Automated Testing​

Upload Files with the REST API​

Below are some examples of how to use the Sauce Labs REST API to upload your mobile file to Sauce Storage. If you do not have a file to test, consider using the Sauce Labs Swag Labs sample app for validating this process.

REST API Authentication​

You can find the authorization credentials at app.saucelabs.com. A recommended best practice is to set your credentials as environment variables, as shown below:

SAUCE_USERNAME='valid.username'
SAUCE_ACCESS_KEY='valid.key'

For specific instructions on how to set environment variables visit the following links:

Accepted File Types​

App Storage recognizes certain file types for different platforms and generic use cases. Here are the accepted file types:

Android Apps (APK): .apk files are recognized as Android apps.

iOS Apps (IPA): .ipa files are recognized as iOS apps.

iOS Apps (APP Bundle): A .zip file will be parsed to determine whether a valid .app bundle exists, and if found, it will be accepted as an iOS app.

For generic use, you can upload and store other file types like pre-run executables, packages, or binaries. Some of the accepted formats for this type of use case include:

  • .js
  • .py
  • .tar
  • .zip
  • .sh
  • .bat

Team Management Sync​

App Storage utilizes a Team Management sync feature that enables user permission schemes. In other words, a Sauce Labs administrator, whether an organization admin or a team admin, can regulate access to individual application files or specific binary/script files. By default, the system shares all uploaded files with the team to which the user belongs. As a user, you can only access files shared with the team in which you contribute/participate unless you hold the role of an organization admin; in this case, you have access to all files in your organization.

To manage access to your organization, navigate to Account > Team Management.

Storage API Endpoints​

There are two main contexts/branches for the storage API:

  • One for working with separate application builds (individual builds, application files, etc.)
  • One for working with apps (groups of application builds with the same unique identifier, belonging to the same platform and team)

For the full list of the available endpoints, see Storage API

Using Application Storage with Automated Test Builds​

After successfully uploading your file to application storage, you need to reference the unique app Identifier (file_id) in your test code to retrieve and use your app for automated tests.

For example, let's assume you've updated a new version of your app using the /upload endpoint. The JSON response would be something like below:

{
   "item":{
      "id":"379c301a-199c-4b40-ad45-4a95e5f30a3a",
      "owner":{
         "id":"286c0fbb0cb644c4a012d505b8a0a1ac",
         "org_id":"c064890612424e34a12fca98ce4f32c6"
      },
      "name":"Android.SauceLabs.Mobile.Sample.app.2.3.0.apk",
      "upload_timestamp":1593450387,
      "etag":"0cf189b1c4c17a56656ada5e2d75cd51",
      "kind":"android",
      "group_id":2807,
      "metadata":{
         "identifier":"com.swaglabsmobileapp",
         "name":"Swag Labs Mobile App",
         "version":"2.3.0",
         "icon":"<long-serial-number>",
         "version_code":13,
         "min_sdk":16,
         "target_sdk":28
      },
      ...
      }
   }
}

Then the file_id would be "id":"379c301a-199c-4b40-ad45-4a95e5f30a3a". If you're unsure of the id of an existing app, you can use the endpoint, along with the necessary parameters to find the desired application.

File Name instead of File ID

You can also use the app name field from the storage API in the app capability. This approach is particularly useful if you uploaded your build to Application Storage via a CI pipeline, and you either don't know the id, or you do not wish to perform JSON parsing in order to retrieve the id. The filename field also includes any supported file that can be uploaded to application storage.

Example of uploading an Android .apk file:

caps.setCapability("app", "storage:filename=<file-name>.apk");

Limitations:

  • File names are NOT unique, therefore they will always default to the latest version.
  • Currently you cannot specify the version of the app using this feature.
  • build capability not supported in VDC at this time.

Updating WebDriver Capabilities​

If you were previously using application stored in sauce-storage, you can convert your existing test capabilities by replacing sauce-storage:myapp with storage:<file_id>.

Example Code Snippets​

These examples assume file_id = c8511dd6-38ec-4f58-b8b9-4ec8c23ad882.

Before

caps.setCapability("app", "sauce-storage:some-app.apk");

After

caps.setCapability("app", "storage:c8511dd6-38ec-4f58-b8b9-4ec8c23ad882");

Uploading to a Remote Location​

There may be situations where you want to install an application from a downloadable remote location (AWS S3 bucket, a GitHub repository, etc.).

Review the following guidelines below before uploading your application:

  1. Make sure your application meets the requirements for Android and iOS Mobile Application Testing.
  2. Upload your application to the hosting location.
  3. Ensure Sauce Labs has READ access to the app URL.
  4. In your test script, enter the URL for the application as the app desired capability. Below are some example snippets:
caps.setCapability("app", "https://github.com/saucelabs/sample-app-mobile/releases/download/2.2.1/iOS.Simulator.SauceLabs.Mobile.Sample.app.2.1.1.zip);

Uploading to Legacy Sauce Storage​

Sauce Storage is our legacy private storage space for apps. Files uploaded will expire seven days after upload, and be removed. You can upload the app you want to test to Sauce Storage using our REST API, and then access it for testing by specifying sauce-storage:myapp for the app capability in your test script. You upload apps using the upload file method of the Sauce Labs REST API.

You can use any REST client; cURL is a convenient command-line option.

US West

$ curl -u $SAUCE_USERNAME:$SAUCE_ACCESS_KEY -X POST -H "Content-Type: application/octet-stream" \
"https://saucelabs.com/rest/v1/storage/$SAUCE_USERNAME/$APP_NAME?overwrite=true" --data-binary @path/to/your_file_name

US East

$ curl -u $SAUCE_USERNAME:$SAUCE_ACCESS_KEY -X POST -H "Content-Type: application/octet-stream" \
"https://us-east-1.saucelabs.com/rest/v1/storage/$SAUCE_USERNAME/$APP_NAME?overwrite=true" --data-binary @path/to/your_file_name

EU Central

$ curl -u $SAUCE_USERNAME:$SAUCE_ACCESS_KEY -X POST -H "Content-Type: application/octet-stream" \
"https://eu-central-1.saucelabs.com/rest/v1/storage/$SAUCE_USERNAME/$APP_NAME?overwrite=true" --data-binary @path/to/your_file_name