Browser testing with Selenium IDE scripts

1. Download and install the Selenium IDE.

   You can download and install the Selenium IDE for Firefox and Chrome users.

   • For Firefox users, add the Firefox addon to the browser. Then, restart the browser as needed.

   • For Chrome users, complete one of the following methods:

     Note: The Selenium IDE Chrome extension is no longer available on the Chrome Web Store.

     • Install the Selenium IDE by using command line or command prompt.

       npm install -g selenium-ide
       selenium-ide
       

       For more information about the installation instructions, see readme file.

     • Download the IDE from the Selenium IDE GitHub releases based on your operating system, and run the application locally.

       Note: The Selenium IDE application records projects in the 3.0 format that the Synthetic PoP BrowserScript playback engine does not support yet.

       To make sure the compatibility, you must manually change the version number in the .side file from 3.0 to 2.0.

       After you save your project in the Selenium IDE application, to edit the .side file manually, complete the following steps:

       1. Open the .side file in a text editor.

       2. Find the version field in the file. The following example shows the appearance of the version field:

              {
                  "id": "some-id",
                  "version": "3.0",
                    ...
              }
          

       3. Change the version to 2.0.

       4. Save the file.

2. Open Selenium IDE from the menu bar. Click Record a new test in a new project link, and record a script by following the instructions.

   When Selenium IDE is recording, it generates a command for each user action in a script.

   

3. Perform test actions to search for the instana keywords in Google.

   Press Enter to move to the search result page. Add a wait condition on this page; right-click the search icon and select Selenium IDE -> Wait For -> Present. Enter a value for the timeout in the Value property to wait until the element displayed, for example, 10000 to wait for up to 10 seconds.

   

4. Add an assertion to verify your test. Add an assert command; right-click on the page and select Selenium IDE -> Assert -> Title.

   Then finish your recordings, click the Stop recording button in Selenium IDE.

   

5. You can add commands such as send keys with the value of ${KEY_ENTER} to type Enter in the search text area.

   Provide a timeout value such as 10000 in the Value property of wait for element present command to wait for a condition. Use the same Target value used in the previous step to locate the search text area web element. This is an important step to ensure your test runs stable and successfully. This is referred to Explicit Waits in the browser testing field. The logic polls the application for a specific condition before it continues to the next command in the code. If the condition is not met before a designated timeout value, a timeout error is displayed.

   Then test your script, click run.

   

6. After recording, save the script into a .side file.

   

For more information, see Selenium IDE Get Started. The complete example can be found in the following section.

Consider using the Instana Synthetic-browser-script local runner to test and debug the recorded script locally. The Synthetic-browser-script local runner provides the same runtime as Instana Synthetics and it can help you to clear cookies or user profiles for each test run.

Then you can create Selenium IDE test on Instana, select Create Synthetic Test -> Browser Script Test -> Switch to Advanced Mode, click Add Script, and upload the .side file.

• If you cannot see the timeline chart in the test results on Instana. You can check whether the test ID is in the suites -> tests property. Without this test ID, your test does not perform playback.

  "suites": [{
      "id": "7de135e9-a6c4-4b39-b28a-092bb0d7cbac",
      "name": "Search Instana",
      "persistSession": false,
      "parallel": false,
      "timeout": 300,
      "tests": ["c0283e5a-8cbd-492f-8b3d-f2476f319264"]
  }],
  

• Instana supports only serialized tests in test suites, and thus the following properties in the Selenium IDE scripts are overwritten by the Instana browser playback engine:

  • "persistSession": false
  • "parallel": false

• You can use available Explicit Wait commands to wait for a condition is met before proceeding with the next command in the code. Explicit Wait is a best practice in browser testing. If the specified condition is not met before a designated timeout value, a timeout error is displayed. Your test fails with an error. The most commonly used wait command is wait for element present. Enter the value for the timeout in milliseconds in the value property.

  {
      "id": "d13e50bd-f698-4a04-9420-701a21dcde8d",
      "comment": "",
      "command": "waitForElementPresent",
      "target": "id=searchform",
      "targets": [],
      "value": "10000"
  }
  

• You can pause for a few milliseconds with the pause command. In the following example, wait time is 3 seconds.

  {
      "id": "60135a5c-6aee-4b9b-86a5-d9d0fa41deb7",
      "comment": "",
      "command": "pause",
      "target": "3000",
      "targets": [],
      "value": ""
  }
  

To validate your test results automatically, you can use assertions and Explicit Wait. If the validation fails, the test result status is displayed as failed. You can monitor test failures with Synthetic Smart Alert.

• You can wait until the required element is present on the UI before a designated timeout with wait for element present, assert element present, or other Explicit Wait commands. Set a value for timeout in the value property of the wait for commands. For the assert commands, the timeout value is 15 seconds.

  {
      "id": "e9a3161a-de29-4557-bbf6-9950c1881425",
      "comment": "",
      "command": "assertElementPresent",
      "target": "linkText=About",
      "targets": [],
      "value": ""
  }
  

• You can use assert title command to validate page titles.

  {
      "id": "46eb59c2-5fd6-4481-b3e8-eaaddab79a69",
      "comment": "",
      "command": "assertTitle",
      "target": "instana - Google Search",
      "targets": [],
      "value": ""
  }
  

• You can use the assert text command to confirm that the text of an element contains the value provided. This command's value property must be an exact string match. Selenium IDE does not support pattern matching for the command.

  {
      "id": "ed733875-5682-4a3b-9a3e-9286f88a62ca",
      "comment": "",
      "command": "assertText",
      "target": "linkText=About",
      "targets": [],
      "value": "About"
  }
  

You can use echo command to print logging message in console logs to help you troubleshoot issues.

{
    "id": "03e23d25-38e3-4051-81ff-740109350ee8",
    "comment": "",
    "command": "echo",
    "target": "Generate a TOTP token from a TOTP key",
    "targets": [],
    "value": ""
}

Most test cases need to scroll on the page to make a web element under focus, visible or clickable. In the Selenium IDE script, you need to use JavaScript for scrolling. Use the runScript or executeScript command to implement scrolling as shown in the following example:

• Scroll to half of the page height:

  {
      "id": "e4d8bc94-cd2c-4648-b64e-952ccfa89aaa",
      "comment": "",
      "command": "runScript",
      "target": "window.scrollTo(0, document.body.scrollHeight/2)",
      "targets": [],
      "value": ""
  }
  

• Scroll to the end of the page:

  {
      "id": "e4d8bc94-cd2c-4648-b64e-952ccfa89aaa",
      "comment": "",
      "command": "runScript",
      "target": "window.scrollTo(0, document.body.scrollHeight)",
      "targets": [],
      "value": ""
  }
  

• Scroll to the beginning of the page:

  {
      "id": "e4d8bc94-cd2c-4648-b64e-952ccfa89aaa",
      "comment": "",
      "command": "runScript",
      "target": "window.scrollTo(0, 0)",
      "targets": [],
      "value": ""
  }
  

• Scroll to the web element and click it:

  Wait until the element is located, then scroll to it, and click it.

  {
      "id": "d13e50bd-f698-4a04-9420-701a21dcde8d",
      "comment": "",
      "command": "waitForElementPresent",
      "target": "id=pnnext",
      "targets": [],
      "value": "20000"
  },
  {
      "id": "b345d354-1d95-45d0-81ab-7c78695ed040",
      "comment": "",
      "command": "runScript",
      "target": "const el = document.getElementById('pnnext'); el.scrollIntoView(); el.click();",
      "targets": [],
      "value": ""
  }
  

  {
      "id": "d13e50bd-f698-4a04-9420-701a21dcde8d",
      "comment": "",
      "command": "waitForElementPresent",
      "target": "css=#pnnext > span:nth-child(2)",
      "targets": [],
      "value": "20000"
  },
  {
      "id": "b345d354-1d95-45d0-81ab-7c78695ed040",
      "comment": "",
      "command": "runScript",
      "target": "const el = document.querySelector('#pnnext > span:nth-child(2)'); el.scrollIntoView(); el.click();",
      "targets": [],
      "value": ""
  }
  

• To double click at the filter area and type keys, you can use following example:

  {
      "id": "60135a5c-6aee-4b9b-86a5-d9d0fa41deb1",
      "comment": "",
      "command": "doubleClickAt",
      "target": "id=repos-list-filter-input",
      "targets": [],
      "value": ""
  }, {
      "id": "60135a5c-6aee-4b9b-86a5-d9d0fa41deb1",
      "comment": "",
      "command": "type",
      "target": "id=repos-list-filter-input",
      "targets": [],
      "value": "instana"
  }
  

• To type Enter key after pausing 3 seconds in the filter area, you can use the following example:

  {
      "id": "60135a5c-6aee-4b9b-86a5-d9d0fa41deb2",
      "comment": "",
      "command": "pause",
      "target": "3000",
      "targets": [],
      "value": ""
  }, {
      "id": "d0239041-5bdf-42be-b920-c5055628f161",
      "comment": "",
      "command": "sendKeys",
      "target": "id=repos-list-filter-input",
      "targets": [],
      "value": "${KEY_ENTER}"
  },
  

In the following example, the Selenium IDE script is used to search for the Instana keywords in a search engine:

{
  "id": "d54cb226-42e2-493a-9965-c05d209da23a",
  "version": "2.0",
  "name": "test-google-search",
  "url": "https://www.google.com",
  "tests": [{
    "id": "c0283e5a-8cbd-492f-8b3d-f2476f319264",
    "name": "search instana",
    "commands": [{
      "id": "cd6aaf21-62f8-4d7f-af0a-5fe8beee8fde",
      "comment": "",
      "command": "open",
      "target": "/",
      "targets": [],
      "value": ""
    }, {
      "id": "f6ef14b9-0f06-4b62-bb29-41c21a298703",
      "comment": "",
      "command": "click",
      "target": "id=APjFqb",
      "targets": [],
      "value": ""
    }, {
      "id": "ed0b72f9-8da9-4413-8088-819b89f1f6dc",
      "comment": "",
      "command": "type",
      "target": "id=APjFqb",
      "targets": [],
      "value": "instana"
    }, {
      "id": "f9746499-1d97-4f83-aa8a-a5419d9e3922",
      "comment": "",
      "command": "sendKeys",
      "target": "id=APjFqb",
      "targets": [],
      "value": "${KEY_ENTER}"
    }, {
      "id": "93939f21-739f-4c84-bb2e-580af6b1bc76",
      "comment": "",
      "command": "waitForElementPresent",
      "target": "css=.zgAlFc svg",
      "targets": [],
      "value": "10000"
    }, {
      "id": "331e3fc1-9baa-4519-9814-3105d6d06937",
      "comment": "",
      "command": "assertTitle",
      "target": "instana - Google Search",
      "targets": [],
      "value": ""
    }]
  }],
  "suites": [{
    "id": "7de135e9-a6c4-4b39-b28a-092bb0d7cbac",
    "name": "Search Instana",
    "persistSession": false,
    "parallel": false,
    "timeout": 300,
    "tests": ["c0283e5a-8cbd-492f-8b3d-f2476f319264"]
  }],
  "urls": ["https://www.google.com/"],
  "plugins": []
}

• Access the user credentials defined in the Instana backend server

  To create a credential with the Synthetic Open API, complete the following steps:

  1. Make sure that you have proper permission setting.
  2. Use Synthetic OpenAPI to create a credential by passing the credentialName and credentialValue variables.

  Then, in your test script, use $secure.credentialName to refer to the created credential, for example, $secure.password or $secure.username. ${} in the Value property in Selenium IDE script is to refer to the predefined variables to distinguish from constant string. $secure.credentialName is how to access user credentials in Instana.

  Note: Only the $secure.credentialName format is supported. The $secure[credentialName] format is not supported.

  {
      "id": "98b7df8f-ec53-47f9-b7a0-0eedbfc64ff0",
      "comment": "",
      "command": "click",
      "target": "id=email",
      "targets": [],
      "value": ""
  }, {
      "id": "83ae509f-4247-4acc-ab99-46ef4c620f4f",
      "comment": "",
      "command": "type",
      "target": "id=email",
      "targets": [],
      "value": "${$secure.username}"
  }
  

• Generate Time-based One-Time Password (TOTP) from a secret key to sign in to the website with two-factor authentication (2FA).

  {
      "id": "ec51296b-4d16-4167-ac83-ba87f89cc0c7",
      "comment": "Generate a TOTP token from a TOTP key",
      "command": "executeScript",
      "target": "return $browser.generateTOTPToken($secure.totpKey);",
      "targets": [],
      "value": "totpToken"
  }, {
      "id": "3cbc306a-ed33-46bf-9923-92752b0466f2",
      "comment": "",
      "command": "type",
      "target": "id=password",
      "targets": [],
      "value": "${totpToken}"
  }
  

You can find the screenshots on the Instana test result details page.

{
    "id": "b49ff289-f041-44f1-836b-ba7e993c3f07",
    "comment": "",
    "command": "executeScript",
    "target": "await $browser.takeScreenshot()",
    "targets": [],
    "value": ""
}

You can use $synthetic.xxxx, $secure.xxx, or $env.xxx to access global variables as shown in the following example.

To use variables in template strings syntax in JavaScript such as the echo command, use standard Node.js syntax, and put the variables in ${}.

{
    "id": "da853ea2-7253-4938-ad2d-9272f4c6d3e2",
    "comment": "",
    "command": "echo",
    "target": "tag1's value is ${$synthetic.tag1}",
    "targets": [],
    "value": ""
}

{
    "id": "26438c58-868d-4d6d-9e6f-dbe9d8f373fd",
    "comment": "",
    "command": "executeScript",
    "target": "$attributes.set('regionName', 'green-region');",
    "targets": [],
    "value": ""
}

The custom attributes set by $attributes API in the script and custom properties defined by customProperties on the test definition can be accessed in the test results with the synthetic.tags metric. You can use the synthetic.tags metric to filter the test results or pass custom value to Smart Alert custom payload .

• Use the Selenium commands runScript and executeScript to invoke advanced browser testing APIs.

  You can use the Selenium commands runScript and executeScript to invoke predefined browser testing APIs and global variables in Instana Browser Testing.

  The difference between executeScript and runScript is that executeScript supports storing the returned value in a variable. You can then assert or echo the variable with ${xxx}. To store the returned value, use the return keyword, and provide a variable name in the value input field.

  {
      "id": "ec51296b-4d16-4167-ac83-ba87f89cc0c7",
      "comment": "Generate a TOTP token from a TOTP key",
      "command": "executeScript",
      "target": "return $browser.generateTOTPToken($secure.totpKey);",
      "targets": [],
      "value": "totpToken"
  }, {
      "id": "3cbc306a-ed33-46bf-9923-92752b0466f2",
      "comment": "",
      "command": "echo",
      "target": "Generated TOTO token ${totpToken}",
      "targets": [],
      "value": ""
  }
  

• Define an environment variable, and use it in the browser testing APIs.

  {
      "id": "10d09a25-d101-43b0-84df-f22265b7cec6",
      "comment": "",
      "command": "storeJson",
      "target": "{\"proxy\": \"<proxy_server>:8080\", \"noproxy\": \"localhost,google.com,192.168.1.0/24\"}",
      "targets": [],
      "value": "proxyConfig"
  },
  {
      "id": "237bd334-d963-4a73-b9bb-4c31f1dce051",
      "comment": "",
      "command": "runScript",
      "target": "await $browser.setProxy(${proxyConfig.proxy}, ${proxyConfig.noproxy});",
      "targets": [],
      "value": ""
  }
  

• Scroll to the web element, and click it.

  You can use Instana browser testing API to implement previous scrolling steps easily. The example shown as below implements the logic of waiting for element present, waiting for element visible, scrollIntoView and click the element. The scrollIntoView function can scroll the element into the visible area of the browser window.

  {
      "id": "b345d354-1d95-45d0-81ab-7c78695ed040",
      "comment": "",
      "command": "runScript",
      "target": "let element = await $browser.waitForAndFindElement(By.xpath(`//a[contains(.,'Customer stories')]`), 30000); await $browser.executeScript(`arguments[0].scrollIntoView()`, element); await $browser.executeScript(`arguments[0].click()`, element)",
      "targets": [],
      "value": ""
  }
  

{
    "id": "2e91846e-037b-473d-a977-7fbdfe52d1a4",
    "comment": "",
    "command": "executeScript",
    "target": "await $browser.addHostnamesToDenylist(['ajax.googleapis.com/ajax/libs/jquery']);",
    "targets": [],
    "value": ""
}

{
    "id": "a418460e-a0a9-4c68-bbd0-fb78d6495e92",
    "comment": "",
    "command": "runScript",
    "target": "await $network.setProxy(${proxyConfig.proxy}, ${proxyConfig.noproxy});",
    "targets": [],
    "value": ""
}

In the following example, Selenium commands invoke Instana browser testing APIs and global variables.

Example on log in and validate the Instana UI