# Overview Welcome to Scandium! To help you navigate your way around Scandium, we have prepared this documentation for your reference. For further help, [Join our slack community](https://join.slack.com/t/scandiumcommunity/shared_invite/zt-22yqencvp-K2l6IfNsL5ig~Je4D3nGyA) [Chat with us on live support](https://tawk.to/chat/63d113c447425128790f8e62/1gnkbaeq4) # Scandium Features & Concepts In this article, we will take a look at the features Scandium offers and some of the terms and concepts you need to get familiar with. **Projects** A project in Scandium is how you organize and manage your resources on Scandium. As a Scandium user, you are able to create multiple projects for different purposes. E.g. you can have a project for your production environment, a project for your staging/testing environment etc. Or perhaps different projects for different teams. When you create an account on Scandium, a default project is created for you, you can rename this project or add new ones. **Test Cases** A test case is a recorded user journey. A test case defines a collection of steps carried out to satisfy a particular user journey. For example, a test case can be created to test how the “Add to Cart” feature of an e-commerce app works. A test case will also often be referred to as a test scenario or simply scenario. Scandium allows you to create as many test cases as you need for your app within a project. **Folders** With folders, you can group related test cases for easier identification. Folders work similarly to the folders on your computer. You can have multiple folders created.\\ **Test Steps** A test case is made up of multiple test steps. When creating/recording a test, each action on your application is converted to a step. A step is also referred to as an Event. Examples of test steps include [click](/supported-actions#click), [type](/supported-actions#form-inputs), mouse scroll, [drag and drop](/supported-actions#drag-and-drop), [navigation](/supported-actions#browser-navigation), [hover/mouseover](/supported-actions#hover), [tab open/close](/supported-actions#multiple-windows-and-tabs), [file upload](/supported-actions#file-upload) etc.\\ **Test Runs** Recording your test case is only half of what needs to be done. The purpose of creating a test case is so you can run/replay the scenario to validate for success or failure. A test run on Scandium shows you the result of executing/running/replaying an existing test case. You can run your test cases using the Scandium Browser Extension (which runs locally on your computer), or run remotely on the Scandium Cloud Runner. \\ ~~NB: At the time of writing this article (07-03-2023), you can only run tests locally.~~ You can now run your tests both locally and remotely. # Setting up your account Get started with Scandium #### Create an account To get started with Scandium, you need to create an account. You can create an account by visiting \\ Fill in your details on the registration form: Enter your Name, Company Name, Role, Email (preferably company email) and password into the provided fields. After filling in all required fields, click on the Create Account Button. ![](https://tawk.link/63d113c447425128790f8e62/kb/attachments/cZpPsLaEr8.png) You’ll be redirected to fill in a One time verification code sent to the registered email address. A mail is to be received from Scandium, the verification code is inputted into the provided boxes, then you should click the verify button. Once the verification is complete, a successful message pops up and you’ll be redirected to the Login page. You’ll be required to Input the valid email address and the created password, then the Login button. #### Install the Scandium Extension Download the [Scandium Chrome Extension from here](https://chrome.google.com/webstore/detail/scandium-test-scenario-re/dokpohocljpghkmobklkccilgdiecgok)
Click on "Add to Chrome", and you are ready to go.\\ If you encounter any issues during the sign up process, please [contact our support ](https://tawk.to/chat/63d113c447425128790f8e62/1gnkbaeq4)for assistance. # Create a test case Recording your first test case with Scandium To create and record a test on Scandium,\\ **Create a new test:** In your project dashboard, click on the "New Test" button to create a new test case. ![](/files/bCS82jYLsvAWqvEtNl3t) Give your test a name and input the starting URL of the website to be tested into the allotted space. ![](https://tawk.link/63d113c447425128790f8e62/kb/attachments/XbKUPuJ1do.png) **Record your test:** To record your test, click on the "Record" button on the Scandium toolbar. This will open up a new window where you can interact with your application.\\ **Interact with your application:** Use your application as you normally would while the Scandium tool records your actions. Click on buttons, input data, and navigate through different pages. **Stop recording:** Once you have completed your test cases, click on the "Stop" button on the Scandium toolbar (located at the bottom right of your recording window).\\ **Save recording:** Once the recording stops, click the save button, the test is saved under “tests”. You would need to change your test case name to the preferred name by clicking (untitled test) before you save the test. To rename the test case, click on the edit button. ![](https://tawk.link/63d113c447425128790f8e62/kb/attachments/1Dg1df5i4t.png) **Replay your test:** Once you are satisfied with your test case, click on the "Replay" button to execute it. The tool will replay all the steps recorded and report any errors or issues that it encounters. The result of each step in the test is displayed right on the test creation page. That's it! With these steps, you should be able to create and record a test case using the Scandium no-code automation tool. # Supported Actions Scandium supports a wide range of actions right out of the box, unlike many other record-and-playback tools. ### Click All click actions are captured during the recording of your test case. ### Hover When recording your test case, you are likely to encounter elements which you need to hover your mouse on before you can interact with a sub-element. This hover action is often difficult to automatically detect because of the way browsers work. However, with Scandium, you can record a hover step by simply right clicking on the element that you need to hover on, then from the contextmenu (i.e right-click menu), select the "Add hover step" option of Scadium.
> *Note: When you add a hover step, there is a chance that the hover action might not be carried out successfully when you run test locally on your machine, depending on the kind of hover technology the element uses. This is because the browser limits scripts from being able to move mouse around physically on your machine for security reasons.* > > *However, you can run this same test **remotely** on our browsers and you can rest assured it will work.* ### Form Inputs Scandium supports interactions with all form elements such as text inputs, checkboxes, radio buttons, select dropdowns, textarea. It also supports a lot of WYSIWYG editors. Scandium has been tested with many popular text editors. > If you find that Scandium doesn't work well with your editor of choice, please contact our support. ### Keypress When you press certain keys such as `Tab`, `Enter` and `Escape`, special attention is given to them, and it is usually recorded as a separate step because they likely perform an action within your page. ### Browser Navigation During your recording, as you move from one URL to another, Scandium captures these navigations. The browser's back and forward buttons are also well-supported. Page reload is also captured and replayed when re-running your tests. ### Drag and Drop Drag and Drop actions within a web page can be of two types: 1. Dragging and dropping one element unto another element (implemented using native HTML5 DragAndDrop API) 2. Dragging and dropping an element to any location on the page (implemented using combination of mouse actions) Scandium supports both types of DragAndDrop out of the box without you having to do anything extra other than just dragging and dropping your items. [Watch a video on Scandium's Drag and Drop support](https://www.youtube.com/watch?v=u281h6j2eSo\&t=3s) ### Native Popups (Alerts) Native alert dialogs can be a big challenge for many test automation tools, but not for Scandium. Not only does Scandium record and replay your interaction with these native popups, Scandium also makes it possible to even make assertions against their content. [Watch to learn how to interact with native alerts](https://www.youtube.com/watch?v=agwZODT5ICU) ### File Upload With Scandium, File upload during your test is a breeze. You don't even need to do anything special other than upload your file normally as you would on your application. Scandium supports both manual selection of files via the `` or dropping files into supported areas. Ordinarily, Scandium has support for a lot of file-handling libraries, but if yours doesn't work, please contact our support. ### Multiple Windows and Tabs Scandium supports capturing your actions even if they span multiple browser tabs or windows. During replay, Scandium will automatically open these additional tabs or windows as needed and replay your actions in them. ### IFrames Scandium has good support for IFrames no matter how deeply nested they are. ### Shadow DOM Scandium supports capturing and replaying actions within Shadow DOM. > If your page's shadow dom is deeply nested beyond one layer, or is nested within nested iframes, you might encounter issues. > > Please contact our support for assistance. # File uploads Capturing and replaying file selection steps in test case recording Scandium has full support for native file upload elements (``). They are captured normally during recording and replay. Whether you upload a single file or multiple files, Scandium is able to capture and replay these selections. For the best file upload experience, upload files that are small in size. Recommended maximum file size: **2MB** In the step settings of the file selection, you can see the uploaded file: ![](/files/UE2R5Xb8QxT3NQDoXlFQ) **NB:** Files uploaded using third-party javascript libraries such as [Dropzone](https://www.dropzone.dev/) etc do not have guaranteed support at this time. # Assertions Validate the correctness of an outcome What is a test without an assertion? Assertions are how we verify that the execution of a step gives an expected outcome. For example, if we are creating a test to test that a user can not log in with an incorrect username and password combination, we will assert that an error message *incorrect username/password* is displayed after clicking on the login button. ### How to assert with Scandium By clicking on the green checkmark (✅) on the Scandium toolbar, the assertion panel is displayed.
There are two broad categories of assertions you can make: 1. Against the page itself 2. Against an element on the page #### Against the page You can assert the value of the page title, the page url, or that the page contains a certain text.
#### Assert against an element on the page You can also select any element on the page to assert against. When you opt to assert against an element on the page, the page is put into inspection mode such that any element you hover your mouse on is highlighted. You can click on any element to assert against it. To assert against an element, on the assertions panel window, click on the big blue button:

Activate assertion for element on a page

Once the button is clicked on, the page is put into inspection mode, you can hover your mouse on any element on the page. You should see the element highlighted with a dotted border around it.

Inspecting an element to be asserted against

Click on the element you want to assert against. Then back on the assertion panel, from the list of commands, choose your desired assertion from the dropdown.

Choose desired element assertion

Currently, you can make the following element assertions: | Assertion type | Description | Extra | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | Element should be visible | Verify that the target element is visible on the page | Applies to all elements | | Element should not be visible | Verify that the target element is not visible on the page | Applies to all elements | | Element should contain text | Verify that the target element **contains** the specified string. | Applies to all elements that can have text | | Element should not contain text | Verify that the target element does not contain the specified string | Applies to all elements that can have text | | Element should be enabled 🆕 | Verify that the target element is enabled. The element must be visible, and must not have the `readonly` or `disabled` property. | Applies to elements that can have the disabled property | | Element should be disabled🆕 | Verify that the target element is disabled. The assertion fails if the element is found to be enabled. | Applies to elements that can have the disabled property | | Element has HTML property 🆕 | Verify that the target element has a given property name and a corresponding matching value. | Applies to all elements | | Element has CSS property 🆕 | Verify that the target element has a given CSS attribute name and a corresponding matching value. | Applies to all elements | | Checkbox should be checked | Verify that the target checkbox element is checked | Applicable when the selected target element is either a checkbox or a radio button | | Checkbox should not be checked | Verify that the target checkbox element is not checked | Applicable when the selected target element is either a checkbox or a radio button | #### Updating an assertion If you added assertions during the recording of your test case, you can update the assertion type or expected value of the assertion from the step settings on your test editor. ![](/files/yp7V7RXE2aFf9WKu4cGu) # Groups Create reusable steps by combining multiple steps into one When you create multiple test cases, you start to notice that there are steps that occur in the same sequence across these multiple test cases. For example, if many of your application features are behind a login wall, for every test you create, the login steps are essential. #### Why create groups? * Grouped steps on Scandium make "reuse" very easy. * You can apply a common operation to the group containing the steps. * Apply an edit once to a group and have it take effect in all tests using the group. #### How to create a group 1. Open anyone of your test cases containing the steps you want to turn into a group. 2. Select all the steps you want to combine by *checking* the checkbox on the step.\\
3. Click on the kebab menu above the steps to reveal an additional options dropdown. 4. From the list, select "Add to group"\\
5. In the opened modal, fill in a title and description for the group, also set if you want the group to be reusable (default). Reusable groups will be available in other tests. 6. Finally, click on the "Create Group" button. The selected steps will now be combined into one.
#### Viewing the steps in a group You can now see the group in the list of steps within the test case. The group is indicated with a *folder* icon, also showing the number of steps within the group.
To view the individual steps within the group, click on the *blue plus* button (➕) Then click on the *eye icon,* this will expand the group, showing the steps inside it.
#### Editing a group Within a test, you can edit the settings of a group just like you would do any other single step. [See settings you can do on a step](/step-settings) #### Duplicating a group In addition to individual step settings on a group, you can also clone a group by using the *Replace with duplicate* settings option.
Here's why you may need to replace a group with a duplicate: In a test, when you edit a reusable group (e.g set a precondition, or change its pre-step delay) that is used in multiple tests, these changes apply across all tests using the group. If you however don't intend for this, but instead, you want the group update to only apply to the current test you are editing, you can replace the group with a duplicate. This will create an exact copy of the group, that will now no longer be cross-updated. You can update the group as you desire, and this change will not propagate to other test cases.
#### Inserting an existing group into a test Now that you have a reusable group, you can insert the group into any test you desire. To do that: 1. Open the test where you want to insert your group 2. *Check* the checkbox of the step occupying the position where you want the group inserted 3. Click on the kebab icon above the steps 4. From the dropdown, select "Insert group Before". 5. From the list of groups displayed, select the group you want to insert. 6. Voila! #### Renaming a group To rename a group: 1. Open any test that uses the group 2. Open the settings of the group step. (➕) => ⚙️ 3. In the title field, insert the new desired name for the group\\

Update group name

#### Deleting/Removing a group from a test To remove a group from within any test using the group, 1. Open the test you want to remove the group from 2. Open the settings of the group step. (➕) => ⚙️ 3. At the bottom of the settings panel, click on the DELETE button\\

Delete a group from a test

#### Adding new steps to an existing group After you have initially created your group with some steps, you might need to later add additional steps to the group. To achieve this: 1. Open the test containing the step(s) you want to add to an existing group 2. *Check* the checkbox on the step(s). 3. Click on the kebab menu, and select "*Add to existing group*"\\

Add one or more steps to group

4. Then from the popup modal, all your existing groups will be listed. From the list, select the group you want to add the selected steps to.\\

Add selected steps to existing group

5. The newly added steps will be added to the end of the group. 6. You can rearrange the steps within a group by dragging the step to the desired position. #### Removing a step from a group You can only remove a step from a group either by "Moving the step to a parent step", or deleting the step. To move a step to the parent (i.e to the test case where the group is being edited), 1. [Expand the group](#viewing-the-steps-in-a-group) to the steps within it 2. Open the settings panel of the step you want to move. (➕) => ⚙️ 3. At the bottom of the settings panel, click on "*Move to Parent*". \\

Move a step to the parent test

***NB: If you remove a step from a group (either by deleting or moving to parent), this will affect the group across all other tests that are using this group. Therefore, use with caution.*** ***If you do not want the changes done to the group within a test to affect other tests using the group,*** [***consider duplicating the group***](#duplicating-a-group) ***to create a local copy.*** # Step settings Customizing an individual step within a test. After recording your test, Scandium allows you review and modify the details of each step within the test. To access the settings of a step, click on the plus (+) button on the step, then click on the settings icon in the expanded options.
This will reveal the settings sidebar. The following are options you can customize on a step. 1. **Title**: A descriptive title for the step 2. **Text to Assign:** The input value of the step (if the target element of the step is an input editable field) 3. **Target element:** CSS Selector string to identify the target element of the step. 4. **Wait mode**: By default, Scandium tries to perform some visibility and actionability check on elements before making actions on the target element. It "waits" for these checks to be true before performing the action of the step. If these checks do not pass, the step fails with either an "`Element was found but wasn't visible`" error or "`Element was found but wasn't actionable`" error. 1. **Element should be visible**: The target element must be visible on the page i.e not hidden, not blocked/covered by another element. 2. **Element should be actionable**: In addition to the target element being visible, it must also be actionable i.e not disabled or have readonly property.\ \ If you uncheck both of these boxes, it means you are instructing Scandium to not check for these conditions before performing the action of the step. This is similar to *forcing clicks* on frameworks like Playwright (`locator.click({force: true})`), Cypress (`cy.get('@closeBtn').click({ force: true })`). 5. **Failure mode (When this step fails):** Determines what should happen to the test if the step fails. There are three (3) modes available: 1. **Fail test immediately:** The test will be aborted and reported as failed. Steps after the failed step will not be executed. 2. **Fail and continue:** The test will be reported as failed, but test will not be aborted. Steps after the failed step will still be executed. 3. **Ignore failure:** The step will simply be ignored. The test will not be reported as failed, and steps after the failed step will be executed. 6. **Precondition mode (When to run this step):** Sets a condition that is first evaluated before determining if the step should be executed or not. If the evaluation of the condition results to true, the step will be executed, otherwise, the step will be skipped. You can set the following conditions on a step: 1. **Always run:** No condition is attached to the step, the step will always run. 2. **Never run (skip):** The step will be skipped during execution. This can be used if you do not want to delete the step permanently. 3. **Element visible:** *This requires an additional css selector.* If the element specified in the selector is found and visible on the page, the step will be executed. If not found, the step will be skipped. 4. **Element not visible:** *This requires an additional css selector.* If the element specified by the selector is visible on the page, the step **will not** be executed, but if not found, the step will be executed. 5. **Element contains text:** *This requires an additional css selector and a string to check for.* If the the element specified by the css selector contains the specified string, the step will be executed. If it doesn't contain the string, the step will be skipped. 6. **Page title matches:** *This requires an additional page title string.* If the specified page title string matches the current page title, the step will be executed, otherwise, the step will be skipped. 7. **Page URL matches:** *This requires an additional URL string.* If the current page URL matches the specified url string, the step will be executed, otherwise, the step will be skipped. 7. **Prestep delay:** To set how long (in milliseconds) should Scandium wait for before attempting to execute the step.\ \&#xNAN;***Reminder: 1000 milliseconds = 1 second*** 8. **Step timeout:** If a target element is not immediately found on a page, Scandium keeps trying to fetch the element until it either finds it or the timeout expires. If and after the timeout expires, Scandium will then report the step as a failure. You can control how long you want to Scandium to wait while attempting to fetch the target element of the step. This property is also in milliseconds. 9. **Scroll into view:** To control what should happen if the target element is not currently within the visible viewport. If this setting is checked, Scandium will scroll to the element and show it within the viewport. 10. **Delete:** To delete a step permanently. Use with caution, this action is irreversible. If you do not intend to permanently delete a step, use the "Never run" precondition. ### Applying settings to multiple steps There are certain customizations that you might need to apply to multiple steps at a time. Settings like: prestep delay, step timeout, failure mode and wait mode. You can achieve this by ticking the checkboxes on the steps you want to edit, then click on the floating options icon (vertical ellipsis), then click on 'Edit' in the dropdown menu. Make the changes you want to apply.

Edit multiple steps at once

# Variables Creating and using dynamic values in your tests ### Creating variables A variable is a value store, whose value can change depending on certain conditions. On Scandium, there are several ways by which you can create a variable, and we will look at each of these methods. **Step Variables** You can assign the *value* or *text content* of a step's target element to a variable. When you assign a `input` type step to a variable, whatever value is entered into the input field will be extracted and stored in the variable. For other step types like `click` , the text content of the step target element will be extracted and assigned to the variable. A variable created from a step can be used (i.e referenced) in subsequent input steps or in assertion values. To create a step variable (i.e assign a step to a variable), in the settings of a step, click on the "Assign to variable" button.

Click on assign to variable button

You will then be prompted to enter a name for the variable. This name is what you will use to reference the variable as we will soon see. When choosing a name for your variable, ensure you choose a name that is easy to read, unique and contains only alphanumeric characters.

Give a name to your variable

Once you enter a name for your variable and save, you will see the variable name now reflecting in the settings panel.
With the above steps, we have created a step variable, we will see shortly how to make use of the variable which we have created. #### Test Variables Test variables are variables created at the test level. They are available to all steps within the test case in which they have been defined. They help you define a value once, and reuse this value in any step within the test. Differences between a step variable and a test variable | Test Variable | Step Variable | | ---------------------------------------- | ------------------------------------------------------------------------------------------------- | | Can be used in all steps within the test | Can only be used in steps that come after the assigning step | | It's value can be known beforehand | It's value is not known before rather. Rather, it's value is extracted from the element of a step | To create a test variable, click on the test settings icon
Then click on the "Test case variable" tab
You can then click on the "Add new variable" to add a new variable. This will provide you with two new fields to enter the variable name and its value.
You can add as many variables as you need, once all has been added, click on the "Save" button. All of the added variables will now be available for you to use in your test steps. ### Using Variables Variables can be *used* in steps that require an input value. This includes steps that of text fields, and assertions that require additional text. To insert a variable into the value of a text, expand the settings panel of an input step, then below the "Text to assign" field, locate the "Insert variable" button and click on it.

Click on insert variable

A modal will come up, from there, you will see a list of all variables available to you for insertion. Each item on the list will also show you information about how the variable was created e.g Test case, step, file, global etc.

Select variable to insert

Once a variable is selected, it will then be inserted into the text to assign field.

A variable inserted.

As you can see, it is wrapped in two curly brackets `{{ }}` . The name of the variable is contained within the brackets, prefixed by the source of the variable e.g *test.* denoting that it's a test case variable, *step.* denoting that it's a step variable, and so on. # System Functions Generate and use dynamic values in your tests Systems functions are very similar to [variables](/variables), but functions are built-in variables that come with Scandium. Functions help you generate dynamic and unique values in your tests. Let's take a quick look at the available functions on Scandium: **Email**: To help you generate unique emails. Useful in cases where you need to test signup flows and you need a unique email each time the test runs. e.g ** **Num**: To help you generate numbers of any length. e.g *19660200324* **Range**: To help generate a number within two boundaries. e.g *236* **Alpha**: To generate letters of the alphabet. You can specify the number of letters needed and even which character set you want the letters to come from. e.g *itKRJ* **Alphanum**: Similar to alpha, but also includes numbers in the generated value. e.g *JlU1ZZcr* **Date**: To generate date value in a desired format. e.g *15/09/2023* **Time**: Generate timestamp value (epoch time). e.g *1694463242839* **Datetime**: To generate datetime value e.g *Mon Sep 11 2023 21:13:50 GMT+0100 (West Africa Standard Time)* **Boolean***:* To generate one of *true* or *false*. ### Using a system function You can insert a function anywhere you can insert a variable. To use a function in the value of a text field, expand the settings of the step where you want to insert the function, then click on the "Insert function" button, and choose the desired function to insert.

Click on insert function button

Select the function to insert

Function inserted

Once you select a function to insert, its notation will be added in the Text to Assign field `{{num(11)}}` . When the test is running and it gets to this step, the notation will be replaced with a randomly generated 11-digit number. # Email Testing Test workflows that involve validating that emails are sent, or extracting content from emails sent. {% hint style="info" %} As of November 12, 2023, Email Testing is a free feature on Scandium {% endhint %} When testing applications, it is common for emails to be triggered by certain actions. E.g When completing your order on an e-commerce website, an email can be sent to you showing the order confirmation. You may want to access your email to confirm that an email was indeed sent to the user, or perhaps click on a link in the email, or even extract a value from the email to be used in later steps within the test. Instead of having to access a 3rd party mail provider during your tests, Scandium has an inbuilt email service that can be used to access emails triggered during your tests. ### Scandium MailBox Service We provision an email inbox for you that is available to you per project i.e each project has its own inbox. In order to receive emails to the inbox of a project, send your emails to an address in the structure `.@testmail.getscandium.com` where \ is a prefix could be any random string, the most important part of the email is the `.@getscandium.com` A real example would be `wJQvB.jeiuigghep@testmail.getscandium.com` where `wJQvB` could be any string (prefix), `jeiuigghep` is the project unique mail ID. Now, regardless of what the prefix is, any email sent to the address that matches \*<.jeiuigghep@testmail.getscandium.com> will be received in the same inbox. Essentially, emails sent to `sdk.jeiuigghep@testmail.getscandium.com` and `testing123.jeiuigghep@testmail.getscandium.com` will be received in the same inbox. An easy way to get the email pattern for your project is to visit the test creation page, then click on the Mail icon
Once you click on the mail icon, then click on the 'copy' icon in the popup revealed.
The copied email can then be used wherever you need to receive email in your app. For example, it can be used in registration forms that need email. If your registration form triggers an email e.g an activation email, Scandium will receive this email for you in the provided inbox. You can access this inbox anytime by clicking on the "Visit mailbox" link as shown in the image above. ### Accessing Emails During Test Recording When recording your test case, after performing an action that is supposed to trigger an email reception, click on the Mail Icon on the Scandium Toolbar in your recording window.

Mail icon on scandium toolbar

This will open up your mailbox. All the emails directed to your project email structure will be found in this mailbox and you can interact with it like any other web page. You can make assertions, do clicks and so on.

Scandium email inbox

### Generating Dynamic Emails A common scenario during testing is testing registration flows where you are required to use a new/unique email for every new registration. Scandium makes this a breeze. By combining the project mail service provisioned for you and the [Systems Functions](/system-functions), you can generate a dynamic and randomized email during every run. We will look at an example below. We have an inbuilt {{time(0)}} function that generates a unix time based on the current time. By using this as the prefix of your Scandium project mail, you get a dynamic email each time (since the time of run will always be different). `{{time(0)}}.lkdhuz1bql@testmail.getscandium.com` #### Steps to using Dynamic Email in a test step 1. Go to the step that needs the dynamic email value 2. Expand the step and click on its settings icon to open its settings sidebar 3. Click on the "Insert Function" below the "Text To Assign" field of the step 4. Select "Email" from the list of functions 5. In the "offset" field, enter 0 or any other number 6. Click on "Insert". This will replace the value in the "Text to Assign" field to something like `{{time(0)}}.lkdhuz1bql@testmail.getscandium.com` 7. Whenever you re-run this step, you will see the email generated looks like `1699823938.lkdhuz1bql@testmail.getscandium.com`. The {{time}} function gets replaced with the actual time value. This is how you achieve dynamic email. # Data-driven Testing Run the same test with different data Data-driven testing is a software testing technique that separates test data from test scripts. It enables testers to reuse test scripts for different sets of data. Scandium provides built-in features to help you run various test data in just one test case by importing your test case in either Excel, CSV, or JSON format into Scandium. When a data source is added to a test case, running the test case will run for each row in the datasets of the uploaded spreadsheet. ### How to import a data source to a test case on Scandium 1. Record your initial test scenario as usual 2. Create a spreadsheet containing your data set from any Office suite software. Ensure the first row of your data set contains the column header names. These columns will be referred to as corresponding variables within your test. Save and download the file on your computer. 3. On Scandium, click the Settings Icon ⚙️ on the test case page.\\
4. Click the "Upload File" button and select the file you want to upload (created from step 2) \\
5. Once the file has been read, its content will be displayed in JSON format in the text editor below the button. Click on the Save button to save your changes.\\
6. Click on the Back arrow to go back to the list of steps\\
### Using imported data as variables within steps Now that a data source is imported and attached to a test case, you need to update the steps in which you desire the columns from the data source to be used. On the test step of where you want the data imported to reflect, click the ⊕ button, the click settings icon ⚙️ of the step
In the “text to assign” text bar, delete the existing text data
Click on the "Insert Variable" button
In the ensuing modal that displays the list of variables you can select, you should see that each header in the spreadsheet you uploaded has now been mapped to a variable name, with an indicator that shows that the variable is from an external file (the data source). Select the appropriate column from the list. Repeat this for all steps that need input from the data source.
Upon selection, the selected variable will be inserted into the "Text To Assign" field of the step
You can now save and run your test. > Note: Data driven testing will trigger multiple test runs for the same test, so be aware of the usage required before using. > > For example, if your spreadsheet contains 101 rows (including the headers), the test will run 100 times anytime you run it. {% hint style="info" %} On the local runner, Scandium will only run the test for the first 10 rows {% endhint %} You can view the result of a data-driven test run by visiting the **Suites Results** menu. # Test Suites Organize your tests in Suites A test suite is a collection of test cases that often share similar rules and configurations. After you have created your test cases, you ideally don't want to run them one by one. Instead, you want to run multiple test cases at a time. Let's look at a few situations where you might want to run a test suite instead of a single test case: 1. You want to run certain critical test cases in your deployment pipeline during deployment. 2. You want to run certain test cases at a scheduled frequency. 3. You want to run all test cases related to a particular module or feature. 4. You want to manually run all or many test cases within a project. The above situations and more can necessitate the need for test suites. You can create different suites for different purposes. Scandium allows you to create and manage test suites easily. #### Creating a test suite Click on the "Suites" menu to go to the test suites page

Suites menu

Then click on "New suite" to create a new suite

Click on new suite button

Give the suite a **name and description** to identify it. **Then add the execution environments** where you want this suite to be executed. By adding multiple exec. environments, you are able to achieve cross-browser testing. Anytime you run the suite, Scandium will run the tests in the suite on the different environments you added. **Select if you want the tests in the suite to run in sequence or in parallel**. Sequential mode will run the tests one after the other, while parallel mode will run multiple tests at the same time. In parallel mode, the order of execution is not guaranteed, so if your tests depend on one another, better to run them in sequence. Scandium will run them in the order they were arranged in the suite. **Add starting url** to the suite. This is optional. If you want to override the starting URL for all tests within the suite, you can provide a URL here. When the suite runs, it will replace the starting URLs of the individual tests with the URL you specified here. **Add** **tests** to the suite. You can then select one or more tests to add to the suite.

Add tests to suite

#### How to run a test suite To trigger a test suite to run manually, click on the kebab menu of the test suite on the suites page.
~~PS: At this time of this writing(8/7/2023), you can only trigger your test suites to run locally.~~ Hurray, you can now your test suites remotely on Scandium 🎉

Run test suite remotely

If "Run Remotely" is greyed out and not clickable for you, please contact us for activation for your account. # Results View and examine the result of your test runs # Test results When you run a test case from the Editor page, you can see the result of each step immediately on the page. ### Viewing all test results From the navigation menu at the top, clicking on the "Runs" menu will take you to the test runs page that lists all the test cases that you have run at least once.

Test runs page

On this page, you can see the number of all test cases you have run (The All Tab). The "Passed" tab shows you the number of test cases that passed, based on the last run done. The "Failed" tab shows you the number of test cases that failed, based on the last run done. You can click on either the Passed or Failed tab to filter for either success of failure. There is also a search box for you to search for any test case. You can also use the date filters to filter the runs based on the last run date. From the list of test cases displayed, if you click on a test case, it displays the run history of the test cases. You will be able to see the result of each time the test ran in the past.

Run history of a single test case

The table displays summary information about each run, namely: the execution environment, the start and finish time, the duration it took and the status of the run. To view an individual run, click on the row of interest. The click takes you to the editor, listing all steps and the respective status for each step.

Test run result

# Suite results # Why did my test fail? When running tests, it is common for them to fail. Failure could be nailed down to two main reasons: 1. A bug has been, an issue has been identified on the application being tested. This is good news for us, as the test is fulfilling the purpose for which it was created. 2. There's a flaw in the way the test was created or designed. When a test fails, Scandium reports the failure with an identified reason for the failure. We will go over common failure types and what could be done to remedy them. 1. Element not found 2. Element was found, but wasn't visible 3. Element was found but wasn't actionable 4. Waited for a response from iframe but no response received 5. Waited for a new page load but no new page load detected 6. Playback window was closed 7. Tab not found 8. Could not find iFrame element ### Failure Types ### Element not found This is the most common error you will come across #### Common causes 1. The page has not finished loading or the application is down 2. The target element has been removed from the page 3. The element's selector (e.g ID) has been changed 4. The previous step passed but the expected action did not occur. For example, if clicking on a Login button during test run is supposed to load a new page, but the username/password has changed. Clicking on the button was successful, but the login action itself wasn't successful, therefore, the next step after the login will fail. 5. The target element takes a while to appear on the page. 6. This could be caused by poor page hydration of the application under test. [Read here for how to handle page hydration issues with Scandium.](/handling-page-hydration-issues) #### What can be done? Check the side-by-side (baseline vs result) screenshot comparison of the step to determine if the element was visible during the test. If the element is visible on the result screenshot, consider adding a delay on the failing step as it could have taken it time to get displayed on the page. You can add a 10-second (10000ms) delay, depending on how long you've observed it takes the element to show up. ### Element was found but not visible The target element of the step exists on the page but is not directly visible to the user. #### Common causes 1. The element is hidden behind another element (e.g covered by a modal) 2. The element has its CSS display property set to `none` or visibility set to `hidden` 3. The height or width of the element is set to 0 4. The opacity of the element is set to 0 5. Another element must be hovered on before the target element is revealed. #### What can be done? Compare the result and baseline screenshots to see if the element is visible. Update the CSS of the app to ensure the element is not hidden in error. You can observe if this element is only temporarily hidden or covered by another element and becomes visible after a little while. If this is the case, you can add a delay to the step to give it enough time to get visible. You can ask Scandium to interact with this element even if it is not 'visible' by updating the step and removing the visibility constraint. You do this by unchecking the '[Element should be visible'](/step-settings) checkbox under 'Element mode' in the step settings. ### Element was found but wasn't actionable The element was found and visible on the page, but it can not be interacted with. For example, the element is 'disabled' #### Common causes The target element has either a `readonly` or `disabled` property. #### What can be done? Update the app to remove the disabled/readonly property. You can ask Scandium to ignore this constraint by unchecking the 'Element should be actionable' checkbox under the 'Element mode' in the step settings of the step. ### Waited for a response from iframe but no response received During recording, the step to be executed was recorded in an iframe, but during re-execution, the iframe did not respond to the execution. #### Common causes 1. The iframe did not load 2. The iframe no longer exists on the page. For example, that same target element is now been rendered directly on the main window instead of inside an iframe. #### What can be done? Re-record the affected step(s) so new updated selectors can be used for the target element. Delete the affected old steps afterwards. ### Waited for a new page load but no new page load detected This error occurs if the last executed step is supposed to result into a new pageload in the browser, but the page load didn't happen. #### Common causes The element that was clicked on during recording caused the page to load, but during re-execution, clicking on the button didn't cause a page load. This could usually indicate that the button's function has changed. #### What can be done? Re-record the affected step and delete the old step. ### Tab not found This error occurs because the tab where the step is to be executed got closed before the step could be executed. # API Testing Scandium makes it easy for you to test your APIs {% content-ref url="/pages/feikxlbN81VO37wKLiMV" %} [Getting Started](/api-testing/getting-started) {% endcontent-ref %} {% content-ref url="/pages/Tq4Z0Q5dh476bqRrTts1" %} [API Suites](/api-testing/api-suites) {% endcontent-ref %} {% content-ref url="/pages/N2yT2amMUozGqoYUFNQX" %} [Scheduling and Monitoring](/api-testing/scheduling-and-monitoring) {% endcontent-ref %} # Getting Started Get started with Scandium's standalone API testing module ### Create a basic API request
On the Scandium API runner interface, you are able to create a new API request. To create an API request, you need to select the method of the request and provide the API URL (endpoint). Press the Send button to initiate the request or press the Save button to save the request. You can change the name/title of the request before and after saving:
Enter the desired name for your test case and press the Save button. #### Try an example request Method Type: GET API URL:

An API request with sample response

#### Additional information on API requests The Scandium API runner interface allows you to add additional information to your API requests where needed. **Query parameters:** Can be added from the 'Params' tab
**Authorization:** Scandium supports multiple authorization types out of the box, including Bearer Token, Basic Auth, API Key, Digest Auth, Oauth 1.0
**Headers:** You can add several header key-values as required by your API
**Body:** Scandium supports multiple body types as payload for your request. This includes: form-data, x-www-form-urlencoded, JSON, XML, Text, HTML and GraphQL.
### Adding assertions to API requests When you make API requests, you want to validate that the request outcome meets your expectations. With Scandium API Runner, you can add assertions to your API tests. To add. these assertions, click on the 'Assertions' tab. You can add assertions for the following: * Status code * Response header * Response body type * Response body content * Request duration
To add an assertion, 1. Select the assertion type. 2. Select a condition for the assertion. 3. Input the value to be checked for.

Select assertion operator/condition

Enter assertion value to check for

You can also combine multiple assertions for one request. ### Viewing API Response After sending your API requests, you can see the response to your requests in the tab below the request area. This tab shows you the status code, the duration of the request, the size of the response and the content of the response. You can view the body of the response in JSON, look at the headers and also inspect the Assertions Result tab for result of the assertions you added.

Response body

Assertion result

### Variables in requests Variables make it easy to reuse a value in multiple API tests. For example, imagine the APIs you are testing have the base url `https://example.com/api`. This part of the URL is common to all endpoints, such that a login endpoint would like `https://example.com/api/login` while a registration endpoint would like `https://example.com/api/register`. Now imagine you want to test these APIs across different environments such as staging, test and production, where all these environments have different base URLs. Normally, you'd have to update all test cases with the specific environment URL each time you want to run your API test against such environment. But if you create the base URL as a variable, you'd only have to make the change once. #### How to create a variable You can create a variable by clicking on the Variable submenu
From the modal that appears, you can then add the names and values for your variables. You can add as many variables as you need.
Click on the Save button to save your newly added variable. #### Using a variable (How to make reference to a variable) Once you have created a variable, it will be available for you to use within your tests. Variables can be used in the endpoint field, headers, parameters and body of the request. To reference a variable, type `{{` (two curly braces), this will bring up a suggestion of the list of variables available, you can then select one from the list.

Choose a variable from the suggestion

Variable plus other string

When the request is sent, the variable (denoted by `{{base_url}}`) will get replaced by its value which in this case is [`https://api.edudream.fr`](https://api.edudream.fr) ### Dynamic values and functions in requests When sending an API request, there could often be situations where you need to send a randomized value to your endpoint. For example, when testing a registration endpoint, you want to have a different email address value sent every time the request is made so that your application doesn't give you a "email already exists" error. This could also apply to phone numbers, usernames etc. Scandium makes it easy for you to achieve this dynamic data input. Similar to the variables in requests, dynamic functions also use the `{{ }}` notation. You can use this dynamic values in your: * URL * Query parameter keys and values * Header keys and values * Body payload * Cookies keys and values To use the dynamic value in an accepted field, type the `{{` where the value is required

Type two opening curly braces

A suggestion popup opens up from which you can then click on the 'Dynamic Values' button. Clicking on the button above shows you a modal containing multiple available functions you can choose from. Below are the functions you can choose from: **Email**: To help you generate unique emails. Useful in cases where you need to test signup flows and you need a unique email each time the test runs. e.g ** **Num**: To help you generate numbers of any length. e.g *19660200324* **Range**: To help generate a number within two boundaries. e.g *236* **Alpha**: To generate letters of the alphabet. You can specify the number of letters needed and even which character set you want the letters to come from. e.g *itKRJ* **Alphanum**: Similar to alpha, but also includes numbers in the generated value. e.g *JlU1ZZcr* **Date**: To generate date value in a desired format. e.g *15/09/2023* **Time**: Generate timestamp value (epoch time). e.g *1694463242839* **Datetime**: To generate datetime value e.g *Mon Sep 11 2023 21:13:50 GMT+0100 (West Africa Standard Time)* **Boolean***:* To generate one of *true* or *false*.
**NB**: In JSON payload, you should still insert the dynamic function inside quotes

Put dynamic functions in quote

# API Suites Organize and manage multiple test cases by putting them into test suites A test suite is a collection of test cases that often share similar rules and configurations. After you have created your test cases, you ideally don't want to run them one by one. Instead, you want to run multiple test cases at a time. Let's look at a few situations where you might want to run a test suite instead of a single test case: 1. You want to run certain critical test cases in your deployment pipeline during deployment. 2. You want to run certain test cases at a scheduled frequency. 3. You want to run all test cases related to a particular module or feature. 4. You want to manually run all or many test cases within a project. The above situations and more can necessitate the need for test suites. You can create different suites for different purposes. Scandium allows you to create and manage test suites easily. ### Create a new test suite 1. Navigate to the API test menu 2. From the dropdown, click on the 'Suites' submenu\\
3. On the Suites page, click on the 'Create Suite' button\\
4. Give your suite a name and description 5. Add the desired test cases to the suite using the + button next to each test case\\
6. Finally, click on the 'Save Test Suite' button to save your suite\\
# Scheduling and Monitoring You can use Scandium to monitor your API endpoints Scheduled API tests are tests that run at predefined times and intervals. For instance, you want to know at every hour if your APIs still work as expected. To schedule API runs with Scandium, you need to [create an API suite](/api-testing/api-suites#create-a-new-test-suite). An API suite is a collection of multiple API tests. When you run this single suite, all test cases contained within the suite will run. {% hint style="info" %} To get the best out of your API tests, you should add [assertions](/api-testing#adding-assertions-to-api-requests) to each test case. {% endhint %} ### How to schedule an API suite To schedule an API suite, open the test suite you want to schedule by click on its name from the list of API suites you have created. Click on the 'Schedule' button
From the ensuing modal, provide a name and description for the schedule, then set the frequency for which you want the suite to be run. You can choose from the options hourly, daily, or specific days of the week.
Then click on the 'Save' button. # Mobile Application Testing Test native mobile apps using Scandium {% content-ref url="/pages/53ReHvzgb6jB6v40AECD" %} [Create a mobile project](/mobile-application-testing/create-a-mobile-project) {% endcontent-ref %} {% content-ref url="/pages/nQMuYszbZsGFlbOzqpbE" %} [Uploading Apps](/mobile-application-testing/uploading-apps) {% endcontent-ref %} # Create a mobile project The first step to testing mobile applications is to create a new mobile project Scandium gives you the ability to test your native mobile applications right within a web browser. With Scandium, you can test both native Android and iOS apps. ### How to create a mobile project Before you can begin to upload mobile apps for testing, you need to create a Mobile project on your Scadium account. On the project creation page, from the "project type" dropdown, select "Mobile" from the list.

Create a mobile project on Scandium

# Uploading Apps # Android Scandium requires the APK bundle containing your application to get started. ### Finding your APK file #### With Android Studio Select **Build** -> **Build APK(s)** -> **Build APK(s)** or **Build** -> **Generated Signed APK** (and following the prompts)

Building with Android Studio

Once the build is complete you can locate the `.apk` file by selecting `locate` in the dialog that appears

Select locate in the dialog to navigate to the apk

or by navigating to ``` {project name}/{app module name}/build/outputs/apk/ ``` #### With Gradle Generate your build with `gradle` by running the `assemble` command for your preferred app build variant e.g. `debug` variant Copy ``` ./gradlew assembleDebug ``` Once the build is complete you can locate the `.apk` file by navigating to ``` {project name}/{app module name}/build/outputs/apk/ ``` ### Converting AAB to APK Scandium currently only supports `apk` files for Android. In order to get your application to work with Scandium you will need to convert your `aab` to an `apk` by making use of the [`bundletool`](https://developer.android.com/tools/bundletool) provided by Google. **Generate Universal APKS** ``` bundletool build-apks --bundle=//{aab name}.aab \ --output=/{your app}/{app name}.apks \ --mode=universal ``` **Generate Single APK file from the Universal APKs** ``` unzip -p /{your app}/{app name}.apks universal.apk > /{your app}/{app name}.apk ``` ### Troubleshooting If you are having trouble running your uploaded Android app in Scandium, we recommend trying to run the same APK on the standard Google-provided Android emulator locally over ADB. Once your emulator is launched and available via `adb devices`, you can install it using the `install` command: ``` adb install -r {your app}.apk ``` or by simply dragging over the `apk` into the emulator window. ## Running apps that are not permitted to run on rooted device? Scandium runs Android emulators that are very similar to the Android emulators provided by Google. So, if you encounter any issue, it's often easier to troubleshoot on the Android emulators locally, and then re-upload to Scandium.The standard Google-provided Android emulators do come with *su*. So, some apps can detect this and have limitations to run on rooted devices. If that is the issue, and you would like your app to run on Scandium, you may detect when your app is running in Scandium and skip your rooted check in that case. For convenience, we set the key "i**sAppetize**" to `true` when streaming apps. Check below for example. {% tabs %} {% tab title="Java" %} **With Intents** The data will be passed as extras into the intent that launches your app, accessible by calling the appropriate get method (based on type) e.g. ```java Intent intent = getIntent() intent.getBooleanExtra("isAppetize", false); intent.getStringExtra("stringKey"); ... ``` **With SharedPreferences** The data will also be stored in SharedPreferences under a file called `prefs.db`. This is accessible by fetching that `SharedPreferences` instance and calling the appropriate get method e.g. ```java SharedPreferences preferences = getApplicationContext().getSharedPreferences("prefs.db", Context.MODE_PRIVATE); preferences.getBoolean("isAppetize", false); preferences.getString("stringKey", null); ... ``` {% endtab %} {% tab title="Kotlin" %} **With Intents** The data will be passed as extras into the intent that launches your app, accessible by calling the appropriate get method (based on type) e.g. ```kotlin intent.getBooleanExtra("isAppetize", false) intent.getStringExtra("stringKey") ... ``` **With SharedPreferences** The data will also be stored in SharedPreferences under a file called `prefs.db`. This is accessibly by fetching that `SharedPreferences` instance and calling the appropriate get method e.g. Copy ``` val preferences = applicationContext.getSharedPreferences("prefs.db", Context.MODE_PRIVATE); preferences.getBoolean("isAppetize", false) preferences.getString("stringKey", null) ... ``` Complex types (e.g. arrays or objects) will automatically be serialized and need to be deserialized manually before using e.g. passing an object: Copy ``` { "obj": { "stringKey": "value", "boolKey": true } } ``` when queried, will return: Copy ``` "{"stringKey":"value","boolKey":true}" ``` {% endtab %} {% endtabs %} # iOS To get started, Scandium requires a .zip or .tar.gz file containing your compressed .app bundle. Scandium currently only supports iOS Simulator builds (**.app**). A simulator build can be run in the iOS Simulator with Xcode. AppStore distribution device builds (**.ipa**) are not currently supported. ## Finding your .app file ### Using Xcode The easiest way to get the iOS Simulator build is to run and build your application in Xcode while targeting an iOS Simulator Once the build is complete and the app is running in the simulator, you can locate the `.app` file by navigating to **Product** -> **Show Build Folder in Finder** -> **Products/Debug-iphonesimulator**

Xcode - show build folder in finder

### Using Xcode Command Line Tools You can also generate the iOS Simulator build of your app by building it directly via the command line using `xcodebuild`. **With .xcodeproj** ```shell xcodebuild -project '{project_name}.xcodeproj' \ -scheme '{scheme_name}' \ -sdk iphonesimulator \ -configuration Debug ``` **With .xcworkspace** ```shell xcodebuild -workspace '{your_workspace_name}.xcworkspace' \ -scheme '{scheme_name}' \ -sdk iphonesimulator \ -configuration Debug ``` The `app` file can then be found under ``` build/Debug-iphonesimulator/ ``` ## Compress your app file Once you have located your `.app` file, Scandium requires it to be in a compressed `zip` or `tar.gz` file e.g. ``` zip -r {app name}.zip {app name}.app ``` ## Troubleshooting If you are having trouble running your uploaded iOS app on Scandium, we recommend trying to run the same app on a simulator provided by Apple in Xcode. # Testing mobile app Record your test case in a mobile emulator within your browser Once you have set up a mobile project and obtained the app bundle for testing ([Check here for how to obtain a test-compatible bundle for your application](/mobile-application-testing/uploading-apps)), the next step is to upload the app into your project. ### How to upload app Within your mobile project 1. Click on the Apps menu\\

Click on Apps menu

This should take you to the apps listing page 2. Click on the "Upload new app" button\\

Upload new app

This reveals a modal where you can choose your app bundle located on your computer. The modal contains instructions for obtaining both iOS and Android app bundles for testing 3. Once file is selected, click on the SAVE button to upload application. This might take a while depending on the size of the file.\ **NOTE: There is a soft limit of 150MB file size. i.e if you upload an app greater than this size, it might not get uploaded.** 4. When your upload is successful, you will find the app listed on the same page\\

App listing showing app name, bundle ID and platform

You can upload multiple apps into a project, and you can also choose to create a different project for each app. ### Create a new test With your app uploaded, on the apps listing page, click on your application. This takes you to the app details page. This page shows you the details of the application such as its name, version code, version name, the author, the platform date it was uploaded and the list of test cases created for the application. You can add a new test case by clicking on the 'New Test' button

Click on new test

### Recording a test On the test creation page, an emulator is loaded alongside a toolbar for additional functions

Emulator and options

The emulator/simulator displayed will be based on the type of application uploaded. An android emulator will be displayed for android applications, while an iOS simulator will be displayed for iOS apps. To begin creating your test, click on the `Record` button. After clicking on the Record button, the app gets installed into the emulator, once installation is complete, recording starts. You can now begin to carry out all the necessary steps needed for your test case. **NB: Everytime you record/run your test, the application will get installed into the device afresh, so you're guaranteed that your testing starts from a clean slate.** Once you are done recording all your steps, click on the 'End Session' button. Scroll to the bottom of the page to view all steps recorded for your test. You can inspect the recorded steps to be sure it captures all you need. Save your test by clicking on the SAVE button. This will prompt you to provide a name for the test case.

Enter a name for your test

Enter a name for your test case, and an optional description. You can leave the default step timeout and prestep delay. Then save your changes by clicking on the Save button. **Run the test recorded by clicking on the 'Run/Replay' button**

Run your test

# Common Testing Scenarios #### Can I reset browser session in between tests? Yes, you can. Scandium provides you with a means to have your tests run from a new and clean browser session by taking advantage of the **incognito/private** browser windows. To have Scandium record and run your tests in incognito windows, you need to turn on the incognito permission in the Scandium extension settings. To have Scandium use incognito window for your tests, grant access to it by: 1. Opening the scandium extensions page: 2. Select "**Allow in incognito**" ![image.png](https://cloud.headwayapp.co/changelogs_images/images/big/000/118/124-53604a56e81e3cafe9898ded5125cffc8104363b.png) Creating and running your tests in incognito window ensures that a test is not affected by stored cookies, sessions, localStorage and other existing local states. It is a very critical step towards having each automated test case self-contain and isolated. #### Are there video tutorials for using Scandium? Yes, you can find the official Scandium tutorials on our Youtube channel: Below are some playlists demonstrating various testing scenarious: 1. 2. #### Can I record tests on Firefox Browser? No. At the moment, the Scandium extension is only available on Google Chrome and other Chromium-based browsers such as Microsoft Edge, Brave Browser and Opera. #### My application uses CAPTCHA, can Scandium handle that? CAPTCHAs are designed to differentiate human users from bots, making them a challenge for automated testing tools like Scandium. Since they intentionally block automated interactions, you’ll need to implement workarounds or disable them during testing. Here are some practical solutions: 1. **Use Test Keys for External CAPTCHA Services** * If you’re using a service like reCAPTCHA, check their documentation for test keys that bypass validation in testing environments. * Alternatively, whitelist your test environment domains to exclude them from CAPTCHA checks. 2. **Disable CAPTCHAs for Tests** * Implement a hidden mechanism (e.g., a secret URL parameter or environment variable) that disables CAPTCHA validation when triggered by your tests. * Configure your system to skip CAPTCHA checks when requests come from known testing IP addresses. 3. **Test in a Controlled Environment** * Disable CAPTCHAs entirely in development or staging environments where automated tests run. By implementing one of these strategies, you can maintain test automation efficiency while ensuring CAPTCHA functionality remains secure in production. #### How can I test email OTP scenarios Tests where you have to get a dynamic verification code from an email inbox can pose a challenge for automation. Luckily, Scandium provides you with an easy solution to handling this. The video below shows a demonstration on how to handle OTP-email scenarios in your tests. {% embed url="" %} #### Can I export my Scandium test steps to other automation frameworks? Yes, Scandium allows you export an test case to any of: * Selenium * Playwright * Puppeteer # Handling Page Hydration Issues At some point, while using Scandium for automated testing, you might come across a situation where Scandium performs an action—like clicking a button or entering text—but nothing actually happens. Or you might notice that text entered into an input field suddenly disappears. One of the most common reasons for this behavior is **poor page hydration** in the application under test. In modern web applications, when a page loads, the browser is often served a **static** version first (just HTML). After that, the **dynamic, interactive** part is loaded and the page becomes fully functional—this process is known as **hydration**. This is common in *Server-Side Rendered* applications. Because Scandium interacts with pages extremely fast, it may start executing actions the moment elements appear, even though the page isn't fully "live" yet. For example, a button might look enabled, but the JavaScript event listeners haven’t been attached yet. Scandium clicks the button, but because nothing is listening for the click, nothing happens. #### How to Spot a Hydration Issue To check if your application is affected by poor hydration: 1. Open Chrome DevTools. 2. In the **Network** tab, throttle the network speed to **Slow 3G**. 3. Reload the page and interact with the element (e.g., click a button or type into a field) as soon as it appears. If the button click doesn’t trigger any action or the typed text gets erased, it’s a clear sign that hydration is not complete before interaction. #### The Right Fix This issue is common right after a page navigation or a page that has just finished loading. The proper solution is to ensure that **interactive elements remain disabled until the page is fully hydrated** and ready to handle user (or test) actions. You can add a reasonable [prestep delay](/step-settings) to the step that interacts with the element waiting for hydration. This improves both user experience and test reliability by giving the page enough time to get hydrated. # Tests and Folders Keep tests organized by saving them into folders All your tests and folders are listed on the "Tests" listing page. #### Creating a folder 1. From the tests listing page, click on "New Folder" at the left sidebar.\\
2. Give your folder a name and save\\
#### Creating a test case inside a folder To create a test case within a folder, click on a folder from the test listing page. On the left sidebar, click on "New test".

New test inside folder

You will then be taken to the test editor to create your test case.
Upon saving the test, it will be located within the specified folder. #### Moving a test to a folder By default, tests that are not created inside a folder will be created in the root folder. To move a test into any desired folder: 1. Click on the kebab menu of the test you want to move 2. From the dropdown, select "Move"\\
3. This will show a modal listing all folders (and subfolders) within the project 4. Select your desired destination from the list\ \\
# Tags Tags are custom labels you add to your tests to help filter and organize your tests. When you label tests with tags, you are categorizing them based on certain shared similarities even if they don't necessarily belong in the same folder/suites. A test case can have multiple tags, you can apply these tags as filter when searching for test cases. For example, you can add a `Critical` label tag to tests that must run in your pipeline. ### Adding/Removing Test Tags 1. On the Tests listing page, click on the options icon of a test 2. Click on 'Tags' from the popup menu\\

Clicks on tags

3. From the appearing modal, type in your desired tag/label name, and press Enter on your keyboard. You can also select from the list of existing tags.\\

Type in tag name

4. Once you have added all your desired tags, click on the 'Save' button.\\
### Filter tests by tag To get test cases based on the tags assigned to them: 1. Go to the test listing page 2. Click on the 'Filters' button\\

Click on Filters

3. On the Filters modal, click on the 'Filter by Tags' dropdown, then select the tags you want to apply to your filter\ \\

Select tags to filter by

Only tests assigned to the selected tags will be displayed, irrespective of the folder they are contained within. # Continuous Integration (CI/CD) Automatically execute your Scandium tests within your existing Continuous Integration/Continuous Deployment pipeline. By using the Scandium REST API, you can execute your e2e test cases and suites from within any of the several popular CI/CD platforms. > To interact with the Scandium Cloud Runner API, you need an API token. You can get one from your profile on dashboard.\ > Visit your profile [https://app.getscandium.com/settings/profile](https://playground.getscandium.com/settings/profile) and copy your API token In order to successfully execute a test case or test suite, you will need following Parameters, in addition to the API TOKEN copied from your profile. Read on for how to get each necessary parameter. **Project ID** Click on the projects dropdown, then click on the "View all" button

view all projects

From the list of projects displayed, click on the options (kebab menu) on the project card, then click on "Copy project id"

copy project id

**Test ID** Applicable when you want to run a single test case. To get a test case's ID, from the tests listing page, find the desired test case, click on its options menu, then click on "Copy test Id"

copy test id

**Suite ID** Applicable when you want to run a test suite. To get a test suite's ID, from the suites listing page, find the desired test case, click on its options menu, then click on "Copy suite id" ## Execute a test Calling this endpoint allows you to immediately run a single test case. ### Request ## Run a single test case `POST` `https://scr.getscandium.com/tests/execute` Body parameter is expected in JSON format #### Headers | Name | Type | Description | | ---------------------------------------------- | ------ | ---------------- | | x-api-token\* | String | API TOKEN | | Content-Type\* | String | application/json | #### Request Body | Name | Type | Description | | --------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | project\_id\* | String | The ID of the project containing the test. This can be copied from your dashboard | | test\_id\* | String | The ID of the test to execute. This can be gotten from the test page | | browser | String |

The browser to run this test on. Allow valued: chrome , firefox and edge.
If this value is not supplied, the default browser on the test

case will be used.

| | strategy | String |

await or callback
Use await to make your runner wait until the test done executing (This can make the request take a long while before returning, depending on the length of the test case). Use callback to return immediately (without the result of the run).
Default value is await

| | variables | String | A JSON object of key:value pairs that can be used to set or override existing global variables used in your test | | screenshot | Boolean |

true or false
To determine if screenshots should be taken for each step in the run.
Note: screenshot will always be taken for a failed step in the test.

| {% tabs %} {% tab title="200: OK " %} ```json { "data": { "result": { "id": "9b034f22-8e0b-4e05-8971-61f81d7bd48a", "starting_url": "https://demoqa.com/automation-practice-form", "source": "remote", "browser": "chrome", "browser_version": "117.0.5938.132", "operating_system": "linux", "operating_system_version": "", "is_mobile": false, "duration": 91667, "started_at": 1705931602516, "finished_at": 1705931694183, "status": "success", "running_status": "completed", "test_id": "9b034f22-8e0b-4e05-8971-61f81d7bd48a", "name": "quick demoqa", "reason": "Test completed", "summary": { "total": 34, "passed": 34, "failed": 0, "skipped": 0, "ignored": 0 } }, "errors": [] }, "message": "Test run completed" } ``` {% endtab %} {% endtabs %} #### Sample request using CURL ``` curl --location 'https://scr.getscandium.com/tests/execute' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'x-api-token: ", "test_id": "", "browser": "chrome", "screenshot": true, "strategy": "callback", "variables": {"username": "sdk", "age": 11}, "retry": 0 }' ``` ## Execute a test suite Calling this endpoint allows you to immediately run a test suite. *A test suite is a collection of multiple test cases grouped for similar purposes*. {% hint style="info" %} **Note:** Executing test suites can take a long time to complete especially if there are so many test cases within the suite, and also depending on the load on our systems at the time of run. Your suite run time will also be affected if you setup multiple execution environments for the suite, as the suite will run all tests for each environment. We’d suggest programming your request to deal with response times up to 10 minutes. If all the suite’s tests are not completed within 10 minutes, the API will send a timeout error (although your tests will still be running in the background). {% endhint %} ### Request `POST` `https://scr.getscandium.com/suites/execute` #### Headers | Name | Type | Description | | ---------------------------------------------- | ---------------- | ----------- | | x-api-token\* | String | API TOKEN | | Content-Type\* | application/json | | #### Request Body | Name | Type | Description | | --------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | project\_id\* | String | The ID of the project containing the test. This can be copied from your dashboard | | suite\_id\* | String | The ID of the suite to execute. This can be gotten from the test page | | strategy | String |

await or callback
Use await to make your runner wait until the suite done executing (This can make the request take a long while before returning, depending on the length of the test case). Use callback to return immediately (without the result of the run).
Default value is await

| | retry | String | Specify the number of times you want a failed test within the suite to be retried. Default is 0. Higher values will increase the time it takes your test to run. | {% tabs %} {% tab title="200: OK Sample response when using await strategy" %} ```json { "data": { "runs": [ { "result": { "id": "l2AF-4096o2MpRLd5CrwX", "source": "remote", "browser": "firefox", "browser_version": "120.0.1", "operating_system": "linux", "operating_system_version": "ubuntu", "is_mobile": false, "duration": 139824, "started_at": 1707079870797, "finished_at": 1707080010621, "type": "suite", "type_id": "9b391ad2-d2e7-4978-9e94-3173d50564d5", "name": "Suite with data", "status": "error", "running_status": "completed", "results": [ { "id": "E4hjzqDAMnU5Pyk68tvB-", "starting_url": "https://demoqa.com/automation-practice-form", "source": "remote", "browser": "firefox", "browser_version": "120.0.1", "operating_system": "linux", "operating_system_version": "", "is_mobile": false, "duration": 29261, "started_at": 1707079876249, "finished_at": 1707079905510, "status": "error", "running_status": "completed", "test_id": "9ae57564-b324-4734-9598-a52b987a2ad1", "name": "demoqa tab to date", "reason": "Element not found", "summary": { "total": 10, "passed": 9, "failed": 1, "skipped": 0, "ignored": 0 }, "test_runs": [ { "step_id": "lqe7kdnm1elzew3a4p9", "status": "success", "time_taken": 3436, "result_screenshot": { "imageDimensions": null, "imageData": "" }, "title": "Setup: https://demoqa.com/automation-practice-form", "end_timestamp": 1707079879688, "start_timestamp": 1707079876252 }, { "step_id": "lqe7kkzg4c5fuhpan78", "status": "success", "time_taken": 818, "result_screenshot": { "imageDimensions": null, "imageData": "" }, "title": "Scroll to element", "end_timestamp": 1707079880507, "start_timestamp": 1707079879689 }, { "step_id": "lqe7ku03wz26kaw7089", "status": "error", "time_taken": 16308, "result_screenshot": { "imageDimensions": null, "imageData": "" }, "title": "Click 22", "error": "Element not found", "end_timestamp": 1707079905191, "start_timestamp": 1707079888883 } ] }, { "id": "AxDq2BLKQHb4ecGhFBc9h", "starting_url": "https://demoqa.com/", "source": "remote", "browser": "firefox", "browser_version": "120.0.1", "operating_system": "linux", "operating_system_version": "", "is_mobile": false, "duration": 21898, "started_at": 1707079914237, "finished_at": 1707079936135, "status": "success", "running_status": "completed", "test_id": "9aa0900e-d3f3-43e1-9696-acf1249640ba", "name": "Demoqa with data", "testData": { "data_params": { "id": 1, "phone": "0909029394", "score": 18, "end_time": "2020-09-03T08:11:01.997Z", "lastname": "Sdk", "topic_id": null, "exam_type": null, "firstname": "Sodeeq", "created_at": "2020-09-03T08:05:14.501Z", "session_id": null, "start_time": "2020-09-03T08:05:14.497Z", "subject_id": 2, "updated_at": "2020-09-03T08:05:14.501Z", "completed_at": "2020-09-03T08:11:01.997Z", "total_questions": null, "recommended_topic": 346 }, "current_index": 0, "total_loops": 3 }, "reason": null, "summary": { "total": 19, "passed": 18, "failed": 0, "skipped": 1, "ignored": 0 }, "test_runs": [ { "step_id": "lp19rhy2uv9ukjru41f", "status": "success", "time_taken": 4326, "result_screenshot": { "imageDimensions": null, "imageData": "" }, "title": "Setup: https://demoqa.com/", "end_timestamp": 1707079918564, "start_timestamp": 1707079914238 }, { "step_id": "lp19rrxy2dxflca3uz4", "status": "success", "time_taken": 180, "result_screenshot": { "imageDimensions": null, "imageData": "" }, "title": "Scroll to element", "end_timestamp": 1707079918745, "start_timestamp": 1707079918565 }, { "step_id": "lp19se046ajhe9gsu84", "status": "success", "time_taken": 1193, "result_screenshot": { "imageDimensions": null, "imageData": "" }, "title": "Click \"Female\"", "end_timestamp": 1707079930187, "start_timestamp": 1707079928994 }, { "step_id": "lp19sqb1f56tpcovzbm", "status": "success", "time_taken": 1182, "result_screenshot": { "imageDimensions": null, "imageData": "" }, "title": "Type \"Mobile Number\"", "end_timestamp": 1707079932563, "start_timestamp": 1707079931381 } ] }, { "id": "yY1rCGEwj4jjgMPZPFqVr", "starting_url": "https://demoqa.com/", "source": "remote", "browser": "firefox", "browser_version": "120.0.1", "operating_system": "linux", "operating_system_version": "", "is_mobile": false, "duration": 20642, "started_at": 1707079943804, "finished_at": 1707079964446, "status": "success", "running_status": "completed", "test_id": "9aa0900e-d3f3-43e1-9696-acf1249640ba", "name": "Demoqa with data", "testData": { "data_params": { "id": 1, "phone": "982938394", "score": 18, "end_time": "2020-09-03T08:11:01.997Z", "lastname": "Sucrey", "topic_id": null, "exam_type": null, "firstname": "Bola", "created_at": "2020-09-03T08:05:14.501Z", "session_id": null, "start_time": "2020-09-03T08:05:14.497Z", "subject_id": 2, "updated_at": "2020-09-03T08:05:14.501Z", "completed_at": "2020-09-03T08:11:01.997Z", "total_questions": null, "recommended_topic": 346 }, "current_index": 2, "total_loops": 3 }, "reason": null, "summary": { "total": 19, "passed": 18, "failed": 0, "skipped": 1, "ignored": 0 }, "test_runs": [ { "step_id": "lp19rhy2uv9ukjru41f", "status": "success", "time_taken": 3523, "result_screenshot": { "imageDimensions": null, "imageData": "" }, "title": "Setup: https://demoqa.com/", "end_timestamp": 1707079947328, "start_timestamp": 1707079943805 }, { "step_id": "lp19stx6gbpvk619j8", "status": "success", "time_taken": 1148, "result_screenshot": { "imageDimensions": null, "imageData": "" }, "title": "Click \"\"", "end_timestamp": 1707079964445, "start_timestamp": 1707079963297 }, { "step_id": "lp19t164dvpnu8rd3qt", "status": "skipped", "time_taken": 1, "result_screenshot": { "imageDimensions": null, "imageData": "" }, "title": "Click \"English\"", "end_timestamp": 1707079964446, "start_timestamp": 1707079964445 } ] }, { "id": "_FsdH9EERc4p6TiUTiF6F", "starting_url": "https://demoqa.com/", "source": "remote", "browser": "firefox", "browser_version": "120.0.1", "operating_system": "linux", "operating_system_version": "", "is_mobile": false, "duration": 23018, "started_at": 1707079971297, "finished_at": 1707079994315, "status": "success", "running_status": "completed", "test_id": "9aa0900e-d3f3-43e1-9696-acf1249640ba", "name": "Demoqa with data", "testData": { "data_params": { "id": 1, "phone": "0239383849", "score": 18, "end_time": "2020-09-03T08:11:01.997Z", "lastname": "Remi", "topic_id": null, "exam_type": null, "firstname": "Ola", "created_at": "2020-09-03T08:05:14.501Z", "session_id": null, "start_time": "2020-09-03T08:05:14.497Z", "subject_id": 2, "updated_at": "2020-09-03T08:05:14.501Z", "completed_at": "2020-09-03T08:11:01.997Z", "total_questions": null, "recommended_topic": 346 }, "current_index": 1, "total_loops": 3 }, "reason": null, "summary": { "total": 19, "passed": 18, "failed": 0, "skipped": 1, "ignored": 0 }, "test_runs": [ { "step_id": "lp19rhy2uv9ukjru41f", "status": "success", "time_taken": 3199, "result_screenshot": { "imageDimensions": null, "imageData": "" }, "title": "Setup: https://demoqa.com/", "end_timestamp": 1707079974497, "start_timestamp": 1707079971298 }, { "step_id": "lp19rrxy2dxflca3uz4", "status": "success", "time_taken": 181, "result_screenshot": { "imageDimensions": null, "imageData": "" }, "title": "Scroll to element", "end_timestamp": 1707079974678, "start_timestamp": 1707079974497 }, { "step_id": "lp19t164dvpnu8rd3qt", "status": "skipped", "time_taken": 0, "result_screenshot": { "imageDimensions": null, "imageData": "" }, "title": "Click \"English\"", "end_timestamp": 1707079994314, "start_timestamp": 1707079994314 } ] }, { "id": "kpLTimp7IH22Z4bbnZ5C0", "starting_url": "https://selectorshub.com/iframe-scenario/", "source": "remote", "browser": "firefox", "browser_version": "120.0.1", "operating_system": "linux", "operating_system_version": "", "is_mobile": false, "duration": 6308, "started_at": 1707080002322, "finished_at": 1707080008630, "status": "success", "running_status": "completed", "test_id": "9ac86c8a-1ba5-4e03-964a-0244568db13a", "name": "3-level nested iframe", "reason": null, "summary": { "total": 3, "passed": 2, "failed": 0, "skipped": 1, "ignored": 0 }, "test_runs": [ { "step_id": "lptkbls9dgilgw8zon", "status": "success", "time_taken": 4754, "result_screenshot": { "imageDimensions": null, "imageData": "" }, "title": "Setup: https://selectorshub.com/iframe-scenario/", "end_timestamp": 1707080007077, "start_timestamp": 1707080002323 }, { "step_id": "lptkcjzvb51k6dt0f3j", "status": "skipped", "time_taken": 0, "result_screenshot": { "imageDimensions": null, "imageData": "" }, "title": "Click Destiny", "end_timestamp": 1707080007077, "start_timestamp": 1707080007077 }, { "step_id": "lptkcozxl6pf6unin4", "status": "success", "time_taken": 1552, "result_screenshot": { "imageDimensions": null, "imageData": "" }, "title": "Type \"Destiny\"", "end_timestamp": 1707080008629, "start_timestamp": 1707080007077 } ] } ], "summary": { "total": 5, "passed": 4, "failed": 1 } } } ], "executions": [ { "env": { "id": "9933d94a-d119-4a24-9264-b8faaf9eb807", "name": "Desktop mini", "width": 1024, "height": 650, "browser": "firefox", "operating_system": "linux", "project_id": "98a22a29-78c2-4f46-bc02-82d391cab0ab", "created_at": "2023-05-19T08:01:19.000000Z", "updated_at": "2023-05-19T08:01:19.000000Z" }, "execution_id": "l2AF-4096o2MpRLd5CrwX" } ] }, "message": "Suite run completed" } ``` {% endtab %} {% endtabs %} ### Sample request using cURL ```url curl --location 'https://scr.getscandium.com/suites/execute' \ --header 'Accept: application/json' \ --header 'x-api-token: ' \ --header 'Content-Type: application/json' \ --data '{ "project_id": "", "suite_id": "", "strategy": "await" }' ``` # Continuous Integration (CI/CD) Automatically execute your Scandium tests within your existing Continuous Integration/Continuous Deployment pipeline. > To interact with the Scandium Cloud Runner API, you need an API token. You can get one from your profile on dashboard.\ > Visit your profile [https://app.getscandium.com/settings/profile](https://playground.getscandium.com/settings/profile) and copy your API token In order to successfully execute a test case or test suite, you will need following Parameters, in addition to the API TOKEN copied from your profile. Read on for how to get each necessary parameter. **Project ID** Click on the projects dropdown, then click on the "View all" button

view all projects

From the list of projects displayed, click on the options (kebab menu) on the project card, then click on "Copy project id"

copy project id

**Suite ID** Applicable when you want to run a test suite. To get a test suite's ID, from the suites listing page, find the desired test case, click on its options menu, then click on "Copy suite id" Check the guides below for specific pipelines: [Azure Devops](/integrations/azure-devops) [Bamboo CI](/integrations/bamboo-ci) [Bitbucket Pipelines](/integrations/bitbucket-pipelines) [Circle CI](/integrations/circle-ci) [Github Actions](/integrations/github-actions) [GitLab CI](/gitlab-ci) [Jenkins](/jenkins) [Travis CI](/travis-ci) # CI/CD pipelines On this page, you will find sample code and ways for integrating Scandium tests into come CI/CI pipeline. > If your CI/CD pipeline example is not provided on this page, please feel free to reach out to us. You can do so via our [slack channel here](https://join.slack.com/t/scandiumcommunity/shared_invite/zt-22yqencvp-K2l6IfNsL5ig~Je4D3nGyA) ### Azure Devops In Azure DevOps, you can use the "HTTP REST" task to make an API call to the Scandium Cloud Runner. Here's an example of how you can achieve this in an Azure DevOps pipeline using the HTTP REST task. Please note the following: 1. Replace ``, ``, ``, and `` with your actual API token, project ID, suite ID, and the name of your service connection, respectively. 2. Make sure you have a service connection configured in your Azure DevOps project that has the necessary permissions to make the API call. This YAML snippet assumes you're using the `HTTP REST` task in Azure DevOps. Ensure that the `HTTP REST` task is available in your organization or project. If not, you might need to install it from the Azure DevOps Marketplace. Assuming you have stored your API token, project ID, and suite ID as pipeline variables, you can use the following YAML snippet as an example: ```yaml trigger: - main pool: vmImage: 'windows-latest' variables: apiToken: '' projectId: '' suiteId: '' steps: - task: UseDotNet@2 displayName: 'Use .NET Core sdk' inputs: version: '3.x' - task: HttpRest@1 displayName: 'Make API call - Run E2E test suite' inputs: connectionType: 'connectedServiceNameARM' connectedServiceNameSelector: 'ConnectedServiceName' method: 'POST' authentication: 'Basic' customHeaders: | Accept: application/json Content-Type: application/json x-api-token: $(apiToken) endpoint: '' # Replace with the name of your service connection urlSuffix: '/suites/execute' body: | { "project_id": "$(projectId)", "suite_id": "$(suiteId)", "strategy": "await" } ``` ### Github Actions In your Github actions workflow, add a job to your YAML file like below: ```yaml # This is a basic workflow to help you get started with Actions name: CI with Scandium # Controls when the workflow will run on: # Triggers the workflow on push or pull request events but only for the "main" branch push: branches: [ "main" ] pull_request: branches: [ "main" ] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: # A workflow run is made up of one or more jobs that can run sequentially or in parallel jobs: # This workflow contains a single job called "build" build: # The type of runner that the job will run on runs-on: ubuntu-latest # Steps represent a sequence of tasks that will be executed as part of the job steps: # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it - uses: actions/checkout@v3 - name: Run Scandium Test run: | response=$(curl -X POST -H "Content-Type: application/json" -H "x-api-token: ${{ vars.API_TOKEN }}" -d '{"project_id": "${{ vars.PROJECT_ID }}", "test_id": "${{ vars.TEST_ID }}","browser": "chrome","screenshot": true,"strategy": "await","variables": {"username": "sdk", "age": 11},"retry": 0}' "https://scr.getscandium.com/tests/execute") status=$(echo "$response" | jq -r .data.result.status) message=$(echo "$response" | jq -r .message) if [ "$status" = "success" ]; then echo "Test ran successfully. Status: $status" else echo "Test ran with failure. Status: $status" exit 1 fi env: CURL_CA_BUNDLE: /etc/ssl/certs/ca-certificates.crt # Set the CA certificates bundle path # - name: Install jq # run: | # sudo apt-get update -y # sudo apt-get install -y jq ``` # Azure Devops This guide will help you integrate Scandium into your Azure DevOps pipeline. You’ll be able to trigger and monitor Scandium test executions directly within your Azure build or release pipelines. ### What You’ll Achieve By the end of this guide, your Azure DevOps pipeline will: * Trigger Scandium test suites. * Display live results and logs in the pipeline UI. *** ### Prerequisites Ensure you have: * A [Scandium](https://getscandium.com) account with: * Your `API_TOKEN` * A `PROJECT_ID` and `SUITE_ID` * An Azure DevOps project and pipeline setup * Basic understanding of YAML-based pipeline configuration *** ### Step 1: Store Secrets in Azure DevOps 1. Go to your project settings in Azure DevOps. 2. Under **Pipelines**, click on **Library**. 3. Create a variable group (e.g., `ScandiumVars`). 4. Add the following secrets and check “Keep this value secret” where applicable: | Variable Name | Value / Description | | -------------- | --------------------------------------- | | `API_TOKEN` | Your Scandium API token | | `PROJECT_ID` | Your Scandium project ID | | `SUITE_ID` | Your Scandium test suite ID | | `HUB_URL` | *(Optional)* Selenium Grid URL | | `STARTING_URL` | *(Optional)* Starting URL for the tests | | `BROWSER` | *(Optional)* `chrome` *(default)* | | `SCREENSHOT` | *(Optional)* `true` or `false` | | `VARIABLES` | *(Optional)* `'{}'` *(as JSON string)* | | `RETRY` | *(Optional)* `0` | | `MAX_ATTEMPTS` | *(Optional)* `30` | | `WAIT_PERIOD` | *(Optional)* `120` | *** ### Step 2: Configure Your YAML Pipeline Add the following tasks to your pipeline YAML file: ``` trigger: branches: include: - main variables: - group: ScandiumVars pool: vmImage: 'ubuntu-latest' steps: - script: sudo apt-get update && sudo apt-get install -y jq displayName: 'Install jq' - script: | SCRIPT_URL="https://raw.githubusercontent.com/GetScandium/files/refs/heads/main/scandium_script.sh" curl -o scandium_script.sh $SCRIPT_URL chmod +x scandium_script.sh displayName: 'Download Scandium Script' - script: ./scandium_script.sh env: API_TOKEN: $(API_TOKEN) PROJECT_ID: $(PROJECT_ID) SUITE_ID: $(SUITE_ID) HUB_URL: $(HUB_URL) STARTING_URL: $(STARTING_URL) BROWSER: $(BROWSER) SCREENSHOT: $(SCREENSHOT) VARIABLES: $(VARIABLES) RETRY: $(RETRY) MAX_ATTEMPTS: $(MAX_ATTEMPTS) WAIT_PERIOD: $(WAIT_PERIOD) displayName: 'Run Scandium Script' ``` *** ### Step 3: Trigger a Pipeline Run Push code or manually trigger the pipeline from Azure DevOps. You’ll see logs from Scandium directly in your pipeline output. *** ### Troubleshooting Tips | Problem | Solution | | --------------------- | ------------------------------------------------------------------------ | | ❌ Missing environment | Ensure secrets are linked in the variable group and referenced correctly | | ❌ Script permission | Ensure `chmod +x` is applied before running the script | | 🕒 Long wait | Adjust `WAIT_PERIOD` and `MAX_ATTEMPTS` | *** *** # Bamboo CI This guide will help you integrate Scandium into your Bamboo CI pipeline. With a few configuration tweaks, you can trigger your automated tests from a Scandium suite directly within your build plans. ### What You’ll Achieve By the end of this guide, your Bamboo build will: * Run Scandium test suites as part of your build plan. * Display test output in your Bamboo build logs. *** ### Prerequisites Before you begin, make sure you have: * A [Scandium](https://getscandium.com) account with: * Your `API_TOKEN` * A `PROJECT_ID` and `SUITE_ID` * Bamboo CI installed and running * Administrator access to create/edit build plans * An agent that has `curl`, `bash`, and `jq` installed *** ### Step 1: Define Variables in Bamboo In your build plan: 1. Navigate to your plan configuration. 2. Click **Actions** > **Configure Plan**. 3. Go to **Variables** and define the following: | Variable Name | Value / Description | | -------------- | ---------------------------------------------------- | | `API_TOKEN` | Your Scandium API token | | `PROJECT_ID` | Your Scandium project ID | | `SUITE_ID` | Your Scandium test suite ID | | `HUB_URL` | *(Optional)* Selenium Grid URL | | `STARTING_URL` | *(Optional)* Starting URL for the tests | | `BROWSER` | *(Optional)* `chrome` *(default)* | | `SCREENSHOT` | *(Optional)* `true` or `false` | | `VARIABLES` | *(Optional)* `'{}'` *(as JSON string)* | | `RETRY` | *(Optional)* Number of retries on failure, e.g. `0` | | `MAX_ATTEMPTS` | *(Optional)* Max polling attempts, e.g. `30` | | `WAIT_PERIOD` | *(Optional)* Polling interval in seconds, e.g. `120` | *** ### Step 2: Add Script Tasks to Run Scandium In your build stage: 1. Add a **Script** task named `Install Dependencies` * Script Body: ``` sudo apt-get update && sudo apt-get install -y jq ``` 2. Add another **Script** task named `Download Scandium Script` * Script Body: ``` SCRIPT_URL="https://raw.githubusercontent.com/GetScandium/files/refs/heads/main/scandium_script.sh" curl -o scandium_script.sh $SCRIPT_URL chmod +x scandium_script.sh ``` 3. Add a **Script** task named `Run Scandium Script` * Script Body: ``` ./scandium_script.sh ``` *** ### Step 3: Trigger a Build You can now trigger your Bamboo plan manually or via a VCS change. Watch the build logs for test output and status. *** ### Troubleshooting Tips | Problem | Solution | | ----------------------------- | ------------------------------------------------------------------------------------- | | ❌ `Missing required variable` | Make sure required plan variables are defined (`API_TOKEN`, `PROJECT_ID`, `SUITE_ID`) | | ❌ `Permission denied` | Ensure the script has execute permission (`chmod +x`) | | 🕒 `Stuck waiting` | Adjust `WAIT_PERIOD` and `MAX_ATTEMPTS` plan variables | *** *** # Bitbucket Pipelines This guide will help you integrate Scandium into your Bitbucket Pipelines workflow. With just a few steps, you’ll be able to run automated tests from your Scandium test suite on every push or PR ### What You’ll Achieve By the end of this guide, your Bitbucket pipeline will: * Automatically run tests from a Scandium suite on every push or PR. * Display test results directly in the Bitbucket Pipelines logs. ### Prerequisites Before you begin, make sure you have: * A [Scandium](https://getscandium.com) account with: * Your `API_TOKEN` * A `PROJECT_ID` and `SUITE_ID` * A Bitbucket repository with Pipelines enabled * A `bitbucket-pipelines.yml` file in your repository ### Step 1: Set Your Bitbucket Repository Variables 1. Go to your Bitbucket repository. 2. Click **Repository settings** > **Repository variables** (under Pipelines). 3. Add the following variables: | Variable Name | Description | | -------------- | ------------------------------------------------------------------------------------------------------------------- | | `API_TOKEN` | Your Scandium API token | | `PROJECT_ID` | Your Scandium project ID | | `SUITE_ID` | Your Scandium test suite ID | | `HUB_URL` | *(Optional)* Selenium Grid URL, if running on your infrastructure | | `STARTING_URL` | *(Optional)* The URL your tests should start from. This will override all tests within the suite you are executing. | ### Step 2: Create or Update Your `bitbucket-pipelines.yml` Create or update your `bitbucket-pipelines.yml` file with the following: ```yaml image: ubuntu:latest pipelines: default: - step: name: Run Scandium Tests caches: - apt script: - apt-get update && apt-get install -y curl jq - SCRIPT_URL="https://raw.githubusercontent.com/GetScandium/files/refs/heads/main/scandium_script.sh" - curl -o scandium_script.sh $SCRIPT_URL - chmod +x scandium_script.sh - ./scandium_script.sh services: - docker deployment: Test artifacts: - test-results/** definitions: variables: BROWSER: "chrome" SCREENSHOT: "true" VARIABLES: "{}" RETRY: "0" MAX_ATTEMPTS: "30" WAIT_PERIOD: "120" ``` ### Step 3: Push to Trigger Once you’ve committed and pushed your pipeline file, Bitbucket will automatically run the pipeline and execute your Scandium test suite. *** ### Troubleshooting Tips | Problem | Solution | | -------------------------------------- | ------------------------------------------------------------------------------------------ | | ❌ `Missing required variable` | Double-check that `API_TOKEN`, `PROJECT_ID`, and `SUITE_ID` are set in your repo variables | | ❌ `Script not found or not executable` | Ensure the `SCRIPT_URL` is valid and script has execution permission (`chmod +x`) | | 🕒 `Stuck waiting` | Adjust `WAIT_PERIOD` and `MAX_ATTEMPTS` in the variable section | # Circle CI This guide will help you integrate Scandium into your CircleCI workflow. With just a few steps, you’ll be able to run automated tests from your Scandium test suite on every push or pull request. ### What You’ll Achieve By the end of this guide, your CircleCI pipeline will: * Automatically run tests from a Scandium suite on every push. * Display test results directly in the CircleCI logs. *** ### Prerequisites Before you begin, make sure you have: * A [Scandium](https://getscandium.com) account with: * Your `API_TOKEN` * A `PROJECT_ID` and `SUITE_ID` * A CircleCI project connected to your repository * A `.circleci/config.yml` file in your project root *** ### Step 1: Set Your CircleCI Environment Variables 1. Go to your CircleCI project dashboard. 2. Navigate to **Project Settings** > **Environment Variables**. 3. Add the following environment variables: | Variable Name | Description | | -------------- | ------------------------------------------------------------------------------------------------------------------- | | `API_TOKEN` | Your Scandium API token | | `PROJECT_ID` | Your Scandium project ID | | `SUITE_ID` | Your Scandium test suite ID | | `HUB_URL` | *(Optional)* Selenium Grid URL, if running on your infrastructure | | `STARTING_URL` | *(Optional)* The URL your tests should start from. This will override all tests within the suite you are executing. | *** ### Step 2: Create or Update `.circleci/config.yml` Create or update your `.circleci/config.yml` file with the following configuration: ```yaml version: 2.1 jobs: run-scandium-tests: docker: - image: cimg/base:stable environment: BROWSER: "chrome" SCREENSHOT: "true" VARIABLES: "{}" RETRY: "0" MAX_ATTEMPTS: "30" WAIT_PERIOD: "120" steps: - checkout - run: name: Install Dependencies command: sudo apt-get update && sudo apt-get install -y curl jq - run: name: Download Scandium Script command: | SCRIPT_URL="https://raw.githubusercontent.com/GetScandium/files/refs/heads/main/scandium_script.sh" curl -o scandium_script.sh $SCRIPT_URL chmod +x scandium_script.sh - run: name: Run Scandium Script command: ./scandium_script.sh workflows: version: 2 test: jobs: - run-scandium-tests ``` *** ### Step 3: Commit and Push Once you’ve committed and pushed your `.circleci/config.yml` file, CircleCI will automatically trigger the workflow and execute your Scandium test suite. *** ### Troubleshooting Tips | Problem | Solution | | -------------------------------------- | ------------------------------------------------------------------------------------------ | | ❌ `Missing required variable` | Ensure `API_TOKEN`, `PROJECT_ID`, and `SUITE_ID` are set in CircleCI environment variables | | ❌ `Script not found or not executable` | Double-check the script URL and ensure you added execution permissions (`chmod +x`) | | 🕒 `Stuck waiting` | Adjust `WAIT_PERIOD` and `MAX_ATTEMPTS` in the config file | *** ### *** # Github Actions This guide will help you integrate Scandium into your GitHub CI/CD pipeline using GitHub Actions. With just a few steps, you’ll be able to run automated tests from your Scandium test suite every time ### What You’ll Achieve By the end of this guide, your GitHub workflow will: * Automatically run tests from a Scandium suite on every push to a chosen branch. * Optionally allow manual runs from the GitHub Actions UI. * Show test results directly in your GitHub Actions logs. *** ### Prerequisites Before you begin, make sure you have: * A [Scandium](https://getscandium.com) account with: * Your `API_TOKEN` * A `PROJECT_ID` and `SUITE_ID` * Access to a GitHub repository * A basic understanding of how GitHub Actions works *** ### Step 1: Set Your GitHub Secrets 1. Navigate to your repository on GitHub. 2. Go to **Settings > Secrets and variables > Actions > Repository secrets**. 3. Add the following secrets: | **Secret Name** | **Description** | | --------------- | ------------------------------------------------------------------------------------------------------------------- | | `API_TOKEN` | Your Scandium API token | | `PROJECT_ID` | Your Scandium project ID | | `SUITE_ID` | Your Scandium test suite ID | | `HUB_URL` | *(Optional)* Selenium Grid URL, if running on your infrastructure | | `STARTING_URL` | *(Optional)* The URL your tests should start from. This will override all tests within the suite you are executing. | ### Step 2: Create Your GitHub Actions Workflow In your repo, create a file at:\ `.github/workflows/run-scandium.yml` Paste the following: ```yaml //yaml file name: Run Scandium Script on: workflow_dispatch: # Allows manual trigger of the workflow push: # Runs on push to a specific branch branches: - bashci # Change this to your desired branch jobs: execute-scandium-script: runs-on: ubuntu-latest env: API_TOKEN: ${{ secrets.API_TOKEN }} PROJECT_ID: ${{ secrets.PROJECT_ID }} HUB_URL: ${{ secrets.HUB_URL }} STARTING_URL: ${{ secrets.STARTING_URL }} SUITE_ID: ${{ secrets.SUITE_ID }} BROWSER: chrome SCREENSHOT: true VARIABLES: '{}' RETRY: 0 MAX_ATTEMPTS: 30 WAIT_PERIOD: 120 steps: - name: Checkout Repository uses: actions/checkout@v3 - name: Install jq run: | sudo apt-get update sudo apt-get install -y jq - name: Download the Scandium Bash Script run: | SCRIPT_URL="https://raw.githubusercontent.com/GetScandium/files/refs/heads/main/scandium_script.sh" curl -o scandium_script.sh $SCRIPT_URL chmod +x scandium_script.sh - name: Run the Scandium Script run: | ./scandium_script.sh ``` ### Step 3: Trigger the Workflow #### Option 1: Automatic Trigger Any time you push to the configured branch (e.g., `bashci`), the workflow will run automatically. #### Option 2: Manual Trigger Go to your repo on GitHub: 1. Click the **Actions** tab. 2. Select `Run Scandium Script`. 3. Click **Run workflow**. ### Troubleshooting Tips | **Problem** | **Solution** | | -------------------------------------- | ---------------------------------------------------------------------------------------- | | ❌ `Missing required variable` | Double-check that `API_TOKEN`, `PROJECT_ID`, and `SUITE_ID` are set correctly as secrets | | ❌ `Script not found or not executable` | Ensure the `SCRIPT_URL` is valid and script has execution permission (`chmod +x`) | | 🕒 `Stuck waiting` | Adjust `WAIT_PERIOD` and `MAX_ATTEMPTS` in the environment variables | # GitLab CI This guide will help you integrate Scandium into your GitLab CI/CD workflow. With just a few steps, you’ll be able to run automated tests from your Scandium test suite on every push or merge request. ### What You’ll Achieve By the end of this guide, your GitLab pipeline will: * Automatically run tests from a Scandium suite on every push or merge request. * Display test results directly in the GitLab CI logs. *** ### Prerequisites Before you begin, make sure you have: * A [Scandium](https://getscandium.com) account with: * Your `API_TOKEN` * A `PROJECT_ID` and `SUITE_ID` * A GitLab repository with CI/CD enabled * A `.gitlab-ci.yml` file in your repository *** ### 🛠️ Step 1: Set Your GitLab CI/CD Variables 1. Go to your GitLab repository. 2. Click **Settings** > **CI/CD** > **Variables**. 3. Add the following variables: | Variable Name | Description | | -------------- | ------------------------------------------------------------------------------------------------------------------- | | `API_TOKEN` | Your Scandium API token | | `PROJECT_ID` | Your Scandium project ID | | `SUITE_ID` | Your Scandium test suite ID | | `HUB_URL` | *(Optional)* Selenium Grid URL, if running on your infrastructure | | `STARTING_URL` | *(Optional)* The URL your tests should start from. This will override all tests within the suite you are executing. | *** ### 📁 Step 2: Create or Update Your `.gitlab-ci.yml` Create or update your `.gitlab-ci.yml` file with the following: ```yaml image: ubuntu:latest variables: BROWSER: "chrome" SCREENSHOT: "true" VARIABLES: "{}" RETRY: "0" MAX_ATTEMPTS: "30" WAIT_PERIOD: "120" stages: - test run_scandium_tests: stage: test script: - apt-get update && apt-get install -y curl jq - SCRIPT_URL="https://raw.githubusercontent.com/GetScandium/files/refs/heads/main/scandium_script.sh" - curl -o scandium_script.sh $SCRIPT_URL - chmod +x scandium_script.sh - ./scandium_script.sh tags: - docker artifacts: paths: - test-results/ ``` *** ### Step 3: Push to Trigger Once you’ve committed and pushed your `.gitlab-ci.yml` file, GitLab will automatically run the pipeline and execute your Scandium test suite. *** ### Troubleshooting Tips | Problem | Solution | | -------------------------------------- | ------------------------------------------------------------------------------------------ | | ❌ `Missing required variable` | Double-check that `API_TOKEN`, `PROJECT_ID`, and `SUITE_ID` are set in your repo variables | | ❌ `Script not found or not executable` | Ensure the `SCRIPT_URL` is valid and script has execution permission (`chmod +x`) | | 🕒 `Stuck waiting` | Adjust `WAIT_PERIOD` and `MAX_ATTEMPTS` in the variable section | *** ### # Jenkins This guide will help you integrate Scandium into your Jenkins pipeline. With just a few steps, you’ll be able to run automated tests from your Scandium test suite as part of your CI/CD process. ### What You’ll Achieve By the end of this guide, your Jenkins job will: * Automatically run tests from a Scandium suite during the build process. * Display test results directly in Jenkins console output. *** ### Prerequisites Before you begin, make sure you have: * A [Scandium](https://getscandium.com) account with: * Your `API_TOKEN` * A `PROJECT_ID` and `SUITE_ID` * Jenkins installed and running * `curl` and `jq` installed on the Jenkins build agent * A Freestyle project or Pipeline job configured in Jenkins *** ### Step 1: Configure Environment Variables in Jenkins You can set environment variables in two ways: #### Option A: Global Jenkins Environment Variables 1. Navigate to **Manage Jenkins** > **Configure System**. 2. Under **Global properties**, check **Environment variables**. 3. Add the following variables: | Variable Name | Description | | -------------- | ------------------------------------------------------------------------------------------------------------------- | | `API_TOKEN` | Your Scandium API token | | `PROJECT_ID` | Your Scandium project ID | | `SUITE_ID` | Your Scandium test suite ID | | `HUB_URL` | *(Optional)* Selenium Grid URL, if running on your infrastructure | | `STARTING_URL` | *(Optional)* The URL your tests should start from. This will override all tests within the suite you are executing. | *** ### Step 2: Add Build Steps in Jenkins Pipeline #### If using a **Pipeline Job**, your `Jenkinsfile` should look like this: ``` pipeline { agent any environment { BROWSER = 'chrome' SCREENSHOT = 'true' VARIABLES = '{}' RETRY = '0' MAX_ATTEMPTS = '30' WAIT_PERIOD = '120' } stages { stage('Checkout Code') { steps { checkout scm } } stage('Install Dependencies') { steps { sh 'sudo apt-get update && sudo apt-get install -y curl jq' } } stage('Download Scandium Script') { steps { sh ''' SCRIPT_URL="https://raw.githubusercontent.com/GetScandium/files/refs/heads/main/scandium_script.sh" curl -o scandium_script.sh $SCRIPT_URL chmod +x scandium_script.sh ''' } } stage('Run Scandium Test') { steps { sh './scandium_script.sh' } } } } ``` *** ### Step 3: Run Your Jenkins Job Trigger your Jenkins job manually or on a git push event. Your Scandium test suite will execute as part of the build process. *** ### Troubleshooting Tips | Problem | Solution | | -------------------------------------- | -------------------------------------------------------------------------------- | | ❌ `Missing required variable` | Ensure `API_TOKEN`, `PROJECT_ID`, and `SUITE_ID` are set in Jenkins env vars | | ❌ `Script not found or not executable` | Double-check the script URL and ensure it has execution permissions (`chmod +x`) | | 🕒 `Stuck waiting` | Adjust `WAIT_PERIOD` and `MAX_ATTEMPTS` in the Jenkinsfile | *** # Travis CI This guide will help you integrate Scandium into your Travis CI pipeline. With just a few steps, you’ll be able to run automated tests from your Scandium test suite every time you push code. ### What You’ll Achieve By the end of this guide, your Travis CI pipeline will: * Automatically run tests from a Scandium suite on every push to your repository. * Display test results directly in the Travis CI logs. *** ### Prerequisites Before you begin, make sure you have: * A [Scandium](https://getscandium.com) account with: * Your `API_TOKEN` * A `PROJECT_ID` and `SUITE_ID` * Access to a GitHub repository connected to Travis CI * A `.travis.yml` file or familiarity with configuring one *** ### Step 1: Set Your Travis Environment Variables 1. Navigate to your project on [Travis CI](https://travis-ci.com/). 2. Go to **More Options > Settings**. 3. Under **Environment Variables**, add the following: | Variable Name | Description | | -------------- | ------------------------------------------------------------------------------------------------------------------- | | `API_TOKEN` | Your Scandium API token | | `PROJECT_ID` | Your Scandium project ID | | `SUITE_ID` | Your Scandium test suite ID | | `HUB_URL` | *(Optional)* Selenium Grid URL, if running on your infrastructure | | `STARTING_URL` | *(Optional)* The URL your tests should start from. This will override all tests within the suite you are executing. | ### Step 2: Update Your `.travis.yml` Add the following to your `.travis.yml` file: ```yaml language: bash os: - linux dist: focal before_install: - sudo apt-get update - sudo apt-get install -y jq curl script: - | SCRIPT_URL="https://raw.githubusercontent.com/GetScandium/files/refs/heads/main/scandium_script.sh" curl -o scandium_script.sh $SCRIPT_URL chmod +x scandium_script.sh ./scandium_script.sh env: global: - BROWSER=chrome - SCREENSHOT=true - VARIABLES='{}' - RETRY=0 - MAX_ATTEMPTS=30 - WAIT_PERIOD=120 ``` ### Push to Trigger Once you've pushed this `.travis.yml` to your repo, Travis will automatically run the pipeline, and your Scandium tests will execute. ### Troubleshooting Tips | Problem | Solution | | -------------------------------------- | -------------------------------------------------------------------------------------- | | ❌ `Missing required variable` | Double-check that `API_TOKEN`, `PROJECT_ID`, and `SUITE_ID` are set in Travis settings | | ❌ `Script not found or not executable` | Ensure the `SCRIPT_URL` is valid and script has execution permission (`chmod +x`) | | 🕒 `Stuck waiting` | Adjust `WAIT_PERIOD` and `MAX_ATTEMPTS` in the environment variables |