Cookie

Overview

As a tester, you may want to upload cookies to your app tests for a variety of reasons including security, compatibility, or functionality. We at HeadSpin absolutely understand that need! This document will provide you with information and walk you through the process of uploading cookies to our Remote Control interface.

Information About Cookie Uploading

Using the cookie tool, you can add, delete, or modify a cookie (modifying is equivalent to adding a cookie with the same name as a previously uploaded one to update it); you can also view a list of all uploaded cookies. The cookie tool is found in the Tools tab of a device’s Remote Control View (go to the sidebar on the right of the view and select Tools; this will take you to the Tools page.) Note that you need the proper permissions to enable the cookie tool; if it does not appear, you may need to ensure your organization has the right permission set up. The associated permission is cookie_management_capability.

A few things to note:

• For iOS devices, the Tools tab will only show if you have the associated Tools testing permission enabled for your org.
• Appium must be started to utilize this tool. There is a 60 minute command timeout with a 30 minute keep-alive when starting Appium this way.
• You must use Chrome on Android devices and Safari on iOS devices.
• You must specify the tab/window to which you want to add your cookie; this is to ensure accuracy in testing, since users have the ability to manually control browsers and browser tabs.
• If you would prefer to copy and paste a full cookie command string, you can use the text input instead of the form builder. Note that you must paste a full and valid cookie command; if the command is invalid, an error banner will appear on the page.
• The form builder input only accepts text and number characters for data field entry.
• iOS does not allow automatic tab switch when selecting tab context, so please remember to manually change it on the device.

How to Upload Cookies

1. Navigate to the Remote Control UI and connect to a device using the Start with Appium option (visible from the dropdown arrow next to the ‘Start’ button).

2. Click on the Tools tab in the toolbar to the right of the Remote Control device view.

3. The cookie tool will be displayed on the Tools page; if you are connected to an iOS device, the cookie tool will be the only tool on the page. An Android device will display additional tools depending on your enabled permissions. Verify your permissions with your organization if you do not see what you expect.

4. Make sure your Appium session is active. If it is not active on this device, the cookie tool will display a banner prompting you to activate your Appium session. Please note that connecting an Appium session can take several minutes.

5. On the device, close any previously opened browsers and launch a new browser window. Ensure you are on the correct tab of the device browser if you have multiple tabs open.

6. In the cookie tool page, click the ‘Refresh Tab List’ button. This will pull cookie data from the current browser page on the device and list it in the List of Cookies area near the bottom of the cookie tool page. This data includes the cookie name, value, domain, path, SameSite settings, expiration time and date, a space for customizing the expiration date if you wish, and a toggle for whether the cookie is Http only or secure model. These data fields are listed when the ‘Form’ toggle is selected under ‘Please select cookie input type’.

7. To upload a cookie of your choosing to the Remote Control session, enter the cookie data in the appropriate fields and then click ‘Add Cookie’. Your cookie will appear at the top of the List of Cookies below the Form fields.

8. Alternatively, to upload a cookie using text input, select the ‘Text Input’ toggle beneath the ‘Please select cookie input type’ heading, then enter the command to add your cookie data. The default command listed as an example is document.cookie=“name=value”. Once this data is entered, click ‘Add Cookie’. Your cookie will appear at the top of the List of Cookies below the text input field.

9. Note that custom cookies added to your Remote Control session, unless a specific expiration date and time are set, will expire at the end of the session.

10. To update a cookie, fill out the text or form data as before, utilizing the same name as a previously added cookie; change the values to reflect the updated data. After clicking ‘Add Cookie’, you will see your new data attach to the previously uploaded cookie, updating it in your list. In the example below, the cookie "userName", which was previously assigned the value of "Value1234", is updated with the value "NewValue".

11. To delete a cookie, click the red ‘X’ icon to the right of a cookie’s entry in the cookie list. This will remove the cookie from the cookie tool’s list.

If you have any questions, please get in touch with your HeadSpin administrator.