Tosca - Using Tricentis' Tosca with HeadSpin
Overview
Tosca is a continuous testing platform using codeless AI, developed by our partners at Tricentis, to assist you with end-to-end testing using screen capture methodology. Tosca allows you to test with several enterprise applications and various mobile devices, including Apple devices, from a Windows PC interface. Tosca’s AI-powered testing tools combined with HeadSpin’s comprehensive data capture and globally available devices makes for a powerful combination to give you the best of testing environments. This guide provides you with instructions for the configuration of a new device within Tosca as well as the creation and running of a new test case. Please note that this guide provides instruction for Tosca v2023.1; for more in-depth documentation or documentation for older versions of Tosca, please refer to Tricentis’ Tosca documentation here.
Scanning a Device and Application
1. Determine the device you are working with. In the Remote Control page of the HeadSpin UI, on the far right side of the screen, each device has a ‘...’ icon. Click this icon and select ‘Automation Configuration’.
2. Within the Automation Configuration pop-up, in the Device Configuration tab, copy the WebDriver URL. Make a note of the device udid as well. You will need this information for Tosca configuration in later steps.
3. In the Tosca interface, click ‘Modules’, then select Scan->Mobile.
4. In the Mobile Scan pop-up that appears, click 'Add Connection'*.
Note*: within the Mobile Scan window, two checkboxes are located at the bottom of the window. One of these checkboxes is 'Run Live View'; we recommend checking this checkbox for ease of use in the Tosca interface when running tests.
Note**: You do not always need to create a connection type, as described above; there is a connection dropdown to select from in the ‘Add Device’ window. If using Tosca 15 or later, the “HeadSpin (Remote)” option is available. The connection you select must come from the same hub address as the device you are attempting to use, so note the Appium address for your device and for your selected connection before confirming your choice of connection. Essentially, you will only need to set up a new connection type if you are connecting to a hub that has not previously been connected to.
5. In the Add Connection window that appears, under the dropdown bar for ‘Type’, select ‘Remote (TMA)’. Paste the device’s WebDriver URL in the box labeled “Enter the Appium Server address”. In the box labeled “Enter a name for your connection”, type a name for your connection. Click 'Add' when you are finished and you will be returned to the Mobile Scan window.
6. In the Mobile Scan window, click 'Add Device'.
7. In the Add Device window that now appears, provide a name for your device in the box.
8. In the Add Device window, enter the device ID (this can be found in the Device tab in HeadSpin UI). Select whether the device is iOS or Android.
Note: With iOS, it is necessary to choose whether the device is real or simulated/emulated (because of iOS capabilities within Appium).
9. When all boxes in the Add Device window have information correctly entered and reviewed, click ‘Add’.
10. You will be returned to the Mobile Scan window. The added device should be listed furthest to the left in the scrollable row of available devices (beside the Add device tile), and should automatically be selected; to confirm it is selected, ensure the desired device is highlighted in blue.
11. In the Mobile Scan window, select the application you wish to test with.
- a) To add a new application, click ‘Add app’.
- b) In the Add application window, select either Native/Hybrid or Web for your application, then click 'Continue'.
- c) Enter a name for the application and the AppActivity and AppPackage (in the case of Android) or Bundle ID (in the case of iOS) for the application. Click 'Add'.
- d) For a web app, after selecting Web and clicking 'Continue' in the Add application window, enter the URL and click 'Add'.
12. With device and application selected, click ‘Connect’ and Tosca will commence connecting to the devcie and app to begin the scan process. Again, as explained in step 4, we recommend selecting 'Run Live View' from the checkboxes at the bottom of the Mobile Scan window. You can also select 'Reset application' if you wish to fully reset the application upon starting your scan.
Note: When a scan takes place in Tosca, a module is created; a module is a building block for creating steps for a test case. Scanning confirms a connection between Tosca and the device and fetches the object/elements available for interaction, as well as the control technicalities.
13. Once the connection is verified, the Connection established window appears. Click 'Scan'.
Creating a Module
These steps assume that you have completed the prior section and successfully begun a scan of a device and application. For the purposes of this guide, the example used for the exception is a mobile app; a web app would function similarly. Also note that you can pull up a live view of the device using HeadSpin's Remote Control view in addition to Tosca's live view function.
1. So long as you have LiveView checked within Tosca, once you have connected to a device with an app ready to scan, the captured device and XScan window containing the Mobile App module will appear.
2. To allow interactive manipulation of the live device view, click 'Select on screen’ in the taskbar at the top of the XScan/Mobile App window. This will allow you to click on the controls you want to automate in the window displaying the live view of the device screen.
3. Click the desired controls/interactions in the screen device view to create a module. The elements selected will appear as components of your new module in the XScan/Mobile App window.
Note: You can rename your mobile app module to whatever you prefer by clicking on the item named 'Mobile App' in the XScan/Mobile App window. The name change will also be reflected in the name displayed at the top of the Mobile App window, but for the purposes of this guide we will continue to refer to it as the Mobile App window.
4. When you have finished working with the current captured view, click ‘Finish Screen’. This step essentially retains your module changes from the current screen and resets the scan to be ready for the next capture. The XScan/Mobile App window will display the message “Go to the next screen and click Scan Screen”.
5. Interact with the device live view to reach the next screen you wish to include in your test module. In the XScan/Mobile App window, click ‘Scan Screen’ to capture the elements/objects of the new screen. Repeat steps 3-6 as necessary to complete your module in its entirety.
Creating a New Test Case in Tosca
1. In the ‘Test Cases’ panel on the left side of the Tosca application window, right-click in the directory tree where you intend for your new test case to be located. A context menu as well as an icon menu will appear. In the icons menu, click the image of a blue folder (‘Create Folder’).
2. With a new folder created, click on the new folder in the directory to bring up the context menu again. Click the blue circling arrow icon to create a new test case.
3. The new test case will appear as a list item in the ‘Details’ panel on the right side of the Tosca window, and the new test case will also appear highlighted within the directory hierarchy in the left pane. You can easily rename your test case while it is highlighted.
4. Right-click your test case in the left pane and select “Search and Add TestStep”. Using this tool you will define the application identified in your test and add steps to your test using data gathered from a previously-built module.
5. The ‘Search and Add TestStep’ window will appear. In the Search and Add TestStep window, click in the search bar and type “open”; from the search results list, select the ‘Open Mobile App’ module; this is a pre-built Tosca test step that launches the application on the device.
6. In the directory pane, under your test case, you will now see ‘Open Mobile App’ listed in the directory. Click ‘Open Mobile App’ and in the right pane you will see an entry for ‘Application’.
7. In the ‘Application’ entry, under the ‘Value’ header, enter the Bundle ID or AppActivity and AppPackage for the application you want to test (if the target is a web application, enter the web address for the application.)
8. To add the actual module test steps you wish to include in your test, you can follow either step:
- Right-click your test case’s ‘Open Mobile App’ entry and, from the context menu, select “Search and Add TestStep”; in the Search and Add TestStep window, search for the name of the module you wish to add and select it.
- In the directory pane on the left, locate the module you wish to add to your test, then click and drag it to your test case to perform a drag and drop transfer of the module.
9. Once the module has been added, click within the module and specify an action value for each step if you so choose (for example ‘click’).
Note: You can add multiple modules to build a test case if you wish. For a deeper understanding of this process, Tosca provides training on this process; please refer to Tricentis' Tosca documentation.
Run a Test Case in Tosca
1. Provide test configuration parameters for your test by clicking on your test case; in the right panel, click the tab labeled ‘Test configuration’.
2. In the Test configuration tab, right-click to bring up the context menu and select 'Create Test configuration parameter'.
Provide the following information for your parameters:
- AppiumServer: enter the WebDriver URL
- AppPath: enter the Bundle ID or AppActivity and AppPackage for the application
- Browser: select the browser, for example, ChromeAndroid (this may be greyed out if it is not applicable)
- DeviceName: enter the udid found in the capabilities section of Device Configuration window of a HeadSpin device; you can find this window by clicking the Automation Configuration ellipsis icon in the HeadSpin Remote Control Device tab.
3. Confirm that your test case’s ‘Open Mobile App’ entry has the correct Application value.
4. Right-click your test case to trigger the context menu and select ‘Run in Scratchbook’. This will run your test!
Other information
In Tosca, AppiumServer stands for the WebDriver URL, and DeviceName stands for the udid. If testing with native applications, do not set a Browser value in the test configuration. Only set this value when testing with a mobile browser.
Regarding Tosca versions:
Tosca 15: HeadSpin capabilities are compatible with this version. This version will work with WebDriver URL as-is and needs no modification. You can set the WebDriver URL with v0/ route directly, as in the following example:
<code class="dcode">https://<host>:<port>/v0/<api token>/wd/hub</code>
Tosca 14.x (the latest version is 14.3): HeadSpin capabilities are compatible with this version. This version of Tosca restricts available Appium versions, so the Appium version must be specified in the WebDriver URL, like so:
<code class="dcode">https://<host>:<port>/v1/appium/<appium version>/<api token>/wd/hub>/code>
We highly recommend updating at least to the latest version of Tosca 14 (14.3) if client-side issues occur, particularly if they are network-related. If your test case needs to be run on a specific Appium version, you can request assistance from HeadSpin in determining the device host box's Appium version.
According to Tricentis’ Tosca documentation, these are the recommendations for Appium server version compatibility:
- Tosca 15 can support any Appium versions, theoretically, since clients can specify Appium version via headspin:appiumVersion in configuration; if you prefer to use a lower version, it can be set manually using that capability.
System requirements for Tricentis Tosca 15
- Tosca 14.3: is recommended for use with Appium Server v1.20.2; for mobile test execution in the cloud, Tricentis recommends Appium Server v1.17.1.
System requirements for Tricentis Tosca
- Tosca 14.2: Appium Server v 1.20.2 and 1.21.0 are compatible. Again, for mobile test execution via cloud, use Appium Server v1.17.1.
System requirements for Tricentis Tosca
- Tosca 14.1: recommended for use with Appium Server v1.18.2.
