Run Oxygen tests with Automate

A step-by-step guide to running Oxygen tests with BrowserStack Automate

BrowserStack's AI-powered low-code testing

Checkout our AI-enabled and intuitive low-code recorder for scalable, reliable test execution

Try Low Code Automation

Oxygen is a GUI test automation framework that you can use to create automation tests. It is designed to create automated test scripts using a no-code approach. Integrating Oxygen with BrowserStack helps you run test scripts recorded using Oxygen on 3000+ real devices and desktop browsers.

In this guide, you will learn to:

• Record your test
• Run your first test
• Run tests in parallel
• Test privately hosted websites
• Organize your tests

Prerequisites

• BrowserStack Username and Access key, which you can find in your account settings. If you have not created an account yet, you can sign up for a Free Trial or purchase a plan.
• Node.js version higher than 12 and lower than 15 installed on your machine.
• NPM installed on your machine.
• Oxygen IDE and the Oxygen Chrome extension is installed to enable test recording.
• Oxygen CLI is installed using the npm install oxygen-cli command.

Record your test

Use the following steps to record a test to open google.com in a Chrome browser tab.

1. In the Oxygen IDE, click the New file:

2. Click the Recording icon as show below to start recording your web test:
   
   

3. Start the Chrome browser, open a new tab. Type google.com and press Enter.

4. Switch to the Oxygen IDE, and click the Recording icon again to stop the test recording.

5. Save the recorded script as test.js.

Based on your requirement, create one recording(.js) file per test case, which you can later combine as part of the test suite folder.

Run your first test

After you record all the tests, place all the test files in your test suite root folder.

1. Use the following template to create a configuration file, oxygen.conf.js, in this folder:

    module.exports = {
   
      suites: [
          {
              name: "Oxygen test suite", 
              // Add a case for every test case in your test suite.   
              cases: [
                  {
                      name:"First test",
                      path: ".test.js"
                  }
              ]        
          }
      ],
      // Change concurrency based on the number of parallels.
      concurrency: 2,
      // Add combinations that you want to test. Number of combinations is 
      // equal to value set in concurrency.
      capabilities: [
          {
              "browserName": "chrome",
              "browserVersion" : "latest",
              "bstack:options":{
                  "buildName": "my first build"
              }
          },
          {
              "browserName": "safari",
              "bstack:options":{
                  "osVersion" : "14",
                  "deviceName" : "iPhone 12",
                  "realMobile" : "true",
                  "buildName": "my first build"
              }
          }
      ],
      // Set your BrowserStack credentials.
      seleniumUrl: 'https://YOUR_USERNAME:YOUR_ACCESS_KEY@hub.browserstack.com/wd/hub',
   
      modules: ['web','log'],
   
      framework: 'oxygen'
     };
   

   Check out the capabilities generator for other capabilities that you can use to test.

2. Run your test using the following command:

     npx oxygen-cli oxygen.conf.js
   

Run tests in parallel

If you plan to run your tests in parallel on different devices, you can set the concurrency parameter in the oxygen.conf.js file to the number of available parallels.

Ensure that the number of browser-OS combinations set in the capabilities section doesn’t exceed the value set in the concurrent parameter. If the number of concurrents are less than the number of browser-OS combinations, some tests might be dropped.

For example, if you are testing on 5 different browser-OS combinations with a concurrency parameter set to 5, 5 threads are started to run all configurations simultaneously.

Test privately hosted websites

BrowserStack enables you to run automated tests on your internal development environments, on localhost, and from behind a corporate firewall. This feature is called “Local Testing”.

Local Testing establishes a secure connection between your machine and the BrowserStack cloud. Once you set up Local Testing, all URLs work out of the box, including HTTPS URLs and those behind a proxy or firewall.

Enabling Local Testing with Automate is a simple two-step process:

1. Establishing a Local Testing connection.
2. Configuring your test suite to run through the Local Testing connection.

Enable Local testing with Automate

You can set up the Local testing connection between your system and BrowserStack cloud by following the steps below:

• Download the appropriate Local testing binary for your system:
  • OS X (10.7 and above)
  • Linux 32-bit
  • Linux 64-bit
  • Windows (XP and above)
• Unzip the binary to a folder/directory on your machine.
• Open your command-line interface and navigate to the folder that contains the Local binary.
• Run the binary using the following command:

./BrowserStackLocal --key YOUR_ACCESS_KEY

BrowserStackLocal.exe --key YOUR_ACCESS_KEY

• Your Local testing connection has now been established. You need to configure your tests test capabilities, as shown in the next section.
• Your machine and BrowserStack Cloud remain connected unless you explicitly end the connection since the Local Testing connection is persistent. Hence, close the connection after test execution is complete.

The Local Testing setup might differ slightly based on your requirements, for example, proxy settings, restricting connections to certain domains, etc. Check out the complete list of flags to set up Local Testing for different environments or network configurations.

Run your local test

Use the following steps to run your local test:

1. Record your test using the Oxygen IDE as explained in the Run your first test section. Ensure that the site you use to create the test is a private website, such as https://localhost.com, etc.

2. Edit your configuration file, oxygen.conf.js to set the local parameter as true:

    ...
    capabilities: [
              {
                  "browserName": "chrome",
                  "browserVersion" : "latest",
                  "bstack:options":{
                      "buildName": "my first build",
                      "local" : "true",
                  }
    ...
   

3. Run your test using the following command:

     npx oxygen-cli oxygen.conf.js
   

Organize your tests for better reporting

Oxygen-cli will automatically update the test session status in your BrowserStack dashboard allowing you to easily spot failing test cases.

For a better navigation and troubleshooting experience, the name of the session in the BrowserStack dashboard can be updated to match the name of the test in your test suite. Add the following hook configuration to your oxygen configuration file.

 ...
 hooks: {

        afterCase: function(caseDef, caseResult) {
          web.execute('browserstack_executor: {"action": "setSessionName", "arguments": {"name":'+JSON.stringify(caseDef.name)+'}}');
        }
    }
 ...

You can organize your automated tests that you run on BrowserStack by projects and builds using the projectName and buildName capabilities in the oxygen configuration file.

Organizing your tests by project, build, and test name gives you multiple advantages when it comes to debugging your tests on the BrowserStack Dashboard. We take a look at the benefits with the help of examples:

• Using the projectName capability lets you filter out only the tests related to that project on the Automate Dashboard.
• Using the buildName capability organizes all test sessions with the same build name, under the same build. You can then access any session in that build by clicking the build in the left pane of the Automate Dashboard.
• Updating the session name enables you to recognize each individual test on the Automate Dashboard by its name. The status for each test indicates which if it has passed or failed. Oxygen automatically marks your tests as passed or failed based on the assertions in your recorded scripts, which can be seen on the Automate Dashboard.

Next Steps

• Set debugging options
• Test behind a proxy