Troubleshooting Guide

System Configuration and Installation

PowerShell Security Issue

Users may encounter the error PSSecurityException after executing appium or appium-doctor. Choose one of the methods below to bypass this problem.

First method: Execution Policy configuration via the command line

Open PowerShell as an administrator and run this command Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine, then approve it by typing A or Y and pressing Enter after the confirmation message appears.

Check this article for more information about PowerShell Script Execution Policy.

Second method: Execution Policy configuration in Settings apps (only Windows 10)

Open Settings then navigate to the For Developers tab under Update & Security.

Scroll down to the PowerShell section then click the Apply button. After that, this section will become blurred.

"Unsupported engine" Error

If you get an Unsupported engine error while Gondola is attempting to download dependencies, it indicates that your version of Node.js is not compatible. We recommend using Node Version Manager to manage your Node.js version. Follow the steps below to install it:

• Download the latest release of NVM for Windows from GitHub. At the time this was written, Node Version Manager 1.1.7 (Aug. 2018) was the latest release.

• Download and extract nvm-setup.zip and double-click on the executable to install it. Once the installation is complete, open a command window and confirm NVM is available by running the following command:

C:\\>nvm version
1.1.7

• To check and install a Node.js LTS version

C:\\>nvm list available
|   CURRENT    |     LTS      |  OLD STABLE  | OLD UNSTABLE |
|--------------|--------------|--------------|--------------|
|    14.9.0    |   12.18.3    |   0.12.18    |   0.11.16    |

C:\\>nvm install 12.18.3

• To use the Node.js LTS version run:

C:\\>nvm use 12.18.3

• Download and install Node Version Manager to manage and install Node versions. You can install it by running the command below.

curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.35.3/install.sh | bash

• To check and install a Node.js LTS version (e.g.: Node.js LTS 12.18.3)

nvm install --lts
nvm use --lts

After installing the latest Node.js LTS version, you can check the Node.js version and install the project's dependencies by running the command below:

node -v
npm i

Appium Doctor

Appium Doctor is a useful tool to check if your environment was properly configured. If you have one of the problems below, try re-configuring your environment variables by following this guide after checking that all the necessary components were installed. If the solution above doesn't work, try to remove and re-install related component such as JDK and Android SDK tools then re-configure the variables. Check this guide for help.

TIP

If any Environment Variables changed, you'll need to re-open the command line windows to reload those variables.

Create a new project

Issue with "npm i"

When you've successfully created a new project, the default shell on your pc (e.g: Powershell, zsh) will start automatically and run npm i to install the necessary packages for the project. Users can also use npm i to re-install the Gondola Framework.

Sometimes, npm i will have an error after successfully creating a new project, such as this one:

You should try to run npm cache clean --force and/or delete the node_modules folder in project's root folder, which contains all downloaded packages, then try running npm i again.

See the documention here for more on the npm cache.

Running Tests

Compatibility between Android SDK Platform-Tools and Appium

Appium (e.g: v1.15.1) is not compatible with some Android SDK Platform-Tools versions (e.g: v29.0.0-5611747). The error message will be displayed as below when user runs the test.

If so, you'll need to upgrade it to the latest Android SDK Platform-Tools version. Follow the steps below to complete this process:

1. Open Android Studio.
2. Open up the SDK Manager by selecting Tools > SDK Manager from the menu bar.
3. Select Android SDK > SDK Tools.
4. The Status of Android SDK Platform-Tools will be shown as Update Available. Click the checkbox then click Apply to update it.
5. Click the OK button in the Confirm Change popup and wait for the installation to complete.

The enter keyword is unable to clear a text field on iOS 12.x:

This method is used for entering a string into a text field. It clears the text field before filling it with characters. When using xCode 11 for testing on iOS versions 12.x, this method will not clear the text field, so the entered text will be in the text field along with the initial text. For example, if the field contains the text "username" and you use enter: john the result will be a text field that contains "usernamejohn"

This issue occurs with Appium and XCode 11. The temporary solution is to use xCode 10 for testing on iOS 12.x. For more information, see the issue report here.

Installing an older version of Gondola Studio

There are times when you might need to run a project created using an older version of Gondola Studio. When that project is opened with Gondola Test Designer using newer version of Gondola Studio, the following error message will be displayed:

If you do not wish to upgrade the project, follow the instructions below to install an older version of Gondola Studio:

1. In Visual Studio Code, click the Extensions icon in the Activity Bar .
2. Look for Gondola Studio in the list of installed extensions.
   
3. Click the Manage icon on the newer version of Gondola Studio.
   
4. Click Install Another Version.
   
5. Select an older version of Gondola Studio to install. Version 1.6.214 supports older versions of Gondola Framework.
6. Reloading Visual Studio Code is necessary to complete the installation. You can do so by clicking on Reload Required which appears on the Gondola Studio extension item after the older version has been installed.
   
7. Now, you can open the project's test files with Gondola Test Designer using the older version of Gondola Studio.