Automation Setup Documentation

This document outlines the necessary steps to set up and configure the automation testing project for the Toolstation app.

Requirements

• Android Studio: Setup and Configuration
• XCode: Installation and Setup
• Environment Variables: Setting Up Environments Variables (in zsh file for macOS)
• Node.js should be installed on your computer.

Automation Project Setup

Follow the steps mentioned below to setup automation testing project on your system

1. Clone the repository

Clone this repo: toolstation-testing-mobile on your system and checkout on the latest develop branch.

2. Install Dependencies

Open the project in VSCode and run command npm install in the terminal.

3. Run Test Application

Before configuring the automation script, go to toolstation mobile project: mobile-app. Make sure you are on the latest develop branch. Then execute the Test-prod app of any region. Once the application is running on the emulator/simulator device, stop the execution.

Kindly refer to this video of how to install test application on emulator/simulator devices.

4. Configure .env file

Follow the steps mentioned down below:

1. Open the cloned toolstation-testing-mobile repository on VS Code IDE.
2. Make sure you are on the latest develop branch. Check it in the Gitkraken.
3. Open .env file.
4. Add the path of mobile-app repository in the MOBILE_APP_REPO_LOCATION environment variable. Follow the steps mentioned in this video to the add path.
5. Add the app version and build number in APP_VERSION_NUMBER and APP_BUILD_NUMBER respectively. You can get the app version and build number from the pubspec.yaml file in mobile_app project. The version object at the top will contain the app version and build number.
6. Add name and version of your android emulator in ANDROID_DEVICE_NAME and ANDROID_VERSION respectively. To verify the name and version of your android emulator, refer to this video.
7. Similarly, add the name and version of your iOS simulator in IOS_DEVICE_NAME and IOS_VERSION. The name and iOS version were writen at the top of your simulator device.
8. For the last environment variable DEFAULT_APP_IDENTIFIER, we only need to update this when we are executing any specific test case. We can leave this as it is for now.

5. Executing the Automation Script

Before running the automation Script, make sure the emulator/simulator device is open and there should be no device connected to the system view USB.

Follow the steps mentined down below to execute the automation scripts on the emulator/simulator device.

1. Make sure the .env file is configured and the test prod aap has been build as mentioned in Install Build Steps section.
2. Make sure the emulator/simulator device is open and running.
3. Delete the allure-results directory if already present in toolstation. (Do not delete allure-report directory)
4. Click on the Run and Debug button in the VSCode IDE of toolstation-testing-mobile project.
5. Click on the button beside the play button to open the option menu and select Run all the tests.
6. Click on the play button at the top-left corner of the IDE.
7. Select the device in which you want to execute the tests (android/ios). Make sure the specific emulator/simulator device is opened before execution.
8. Select the region for which you want to execute the tests (uk/be/nl). Make sure the test prod app has been build for the region before execution.
9. Upon selecting the region, the smoke tests scriots will be executed and the logs will be visible on the console.

If you have confusion/concerns about the steps mentioned above, kindly refer to the video on how to execute smoke script for release.

We also have several commands to execute an automation script on specific devices and regions. Refer to the nomenclature for the command to execute the automation script.

npm run wdio [device] [region]

Examples:

The below command will execute the script on Android device for region UK

npm run wdio android uk

Similary, to execute the script on iOS for NL region, we should use:

npm run wdio ios nl

All these commands will execute all the writtent test cases in the automation scripts. To execute any single test case or group, refer to the steps given below.

How to execute single test case/group

To execute single, follow the steps mentioned below:

1. Update the apk file name in appium:app object.
   1. Open wdio.env.js file.
   2. In the constructor, locate capabilities object.
   3. Now, update the apk file name on appium:app object. Add the name of the file for which you want to execute the test case.
      
      Eg. If you want to execute some tests for BE region, then the value of appium:app object will be process.env.MOBILE_APP_REPO_LOCATION + '/build/app/outputs/flutter-apk/app-beprod-debug.apk'
      
      

      Note: Notice that only app-beprod-debug.apk changes, rest remain unchanged. We only need to update the apk file name for each region when executing single test cases.

2. Refer to the list of apk files that you may need to update for each region.
   • UK: app-ukprod-debug.apk
   • BE: app-beprod-debug.apk
   • NL: app-nlprod-debug.apk
3. In the same capabilites object, there may be two capabilities, one for Android and the other for iOS. Refer to the screenshot given below:
   We need to comment out the one which we don't want to execute. At a time, execute the script on any single device.
   
   

   Note: We only need to update the apk file name on Android capabilites. For iOS, we don't need to update the app file name as for all regions, there is only one file on iOS: Runner.app.

4. Open .env file and update object DEFAULT_APP_IDENTIFIER with the app_id for the region that you want to execute the scripts. Refer to the list below for the app_ids of each region and device.
   
   For Android:
   • UK: com.toolstation.mobile_app
   • BE: com.toolstation.mobile_app.be
   • NL: com.toolstation.mobile_app.nl
   
   For iOS:
   • UK: com.toolstation.mobile-app
   • BE: com.toolstation.mobile-app.be
   • NL: com.toolstation.mobile-app.nl
5. Once the above steps are completed, use the 'Run & Debug' option or the 'mocha commands' to execute specific test cases on emulator/simulator devices.
   
   Execute scripts using 'Run & Debug' option
   1. Click on 'Run & Debug' option from the left menu on VSCode IDE.
   2. Beside the play button on the top-left panel, click on the options.
   3. Select, 'Run specific test' option.
   4. Click on the play button.
   5. Enter test case id, group id or page id to execute the test scripts.
   
   Execute scripts using 'mocha commands' 6. Open terminal on VSCode IDE. 7. Use the mocha command given below to execute test script shell npx wdio --mochaOpts.grep [test case id/ group id/ page id] Eg: shell npx wdio --mochaOpts.grep SI_1_1.2 // Will only execute test case with id 'SI_1_1.2'

6. Common Issues & Solutions

1. Issues during first execution:
   On executing the script for the first time, there might be few issues encountered on the console. Follow the steps given below to solve the issues:
   • ECONNREFUSED 127.0.0.1:4723:
   
   To solve this error, execute command:

   killall -KILL node         // For MacOS
   

   taskkill /F /IM node.exe   // For Windows
   

   
   After the above command is executed, run the automation script again and check.
2. Issues while installing the app on physical/emulator/simutor device:
   While installing the builds, if you face any issues or the installation failed and you see an error message on the debug console of your IDE, execute the command given below on the terminal of mobile_app project.

   flutter clean && flutter pub get
   

3. Issues while installing the app on iOS device:
   If the iOS app is not installing and you see error messages on the debug console, follow the steps given below:
   1. Open the mobile_app project on VS Code IDE.
   2. Locate Podfile.lock file in ios directory.
   3. Delete Podfile.lock file.
   4. Open the terminal, on the IDE.
   5. Now, go to ios directory using this command: cd ios.
   6. Execute this command: pod install.
   7. This will create a new Podfile.lock file with all the required dependencies.

If you face further issues regarding installing the app on any device, kindly reach out the flutter team for solutions.

If you face further issues regarding the setup and execution, kindly refer to this documentation for common issue and solutions.