Setup - qxf2/qxf2-page-object-model GitHub Wiki

The setup for our open-sourced Python test automation framework is fairly simple. Don't get fooled by the length of this section. We have documented the setup instructions in detail so even beginners can get started.

The setup has four parts:

  1. Prerequisites
  2. Setup for GUI/Selenium automation
  3. Setup for Mobile/Appium automation
  4. Setup for API automation
  5. Setup for Windows automation

1. Prerequisites

a) Install Python 3.x

b) Add Python 3.x to your PATH environment variable

c) If you do not have it already, get pip (NOTE: Most recent Python distributions come with pip)

d) pip install -r requirements.txt to install dependencies

If you ran into some problems on step (d), please report them as an issue or email Arun([email protected]).

2. Setup for GUI/Selenium automation

Starting with Selenium 4.10, there's no need to manually download browser drivers, as Selenium manager is integrated with selenium. It now automatically downloads both the browser and the driver if they are not already installed. By default, all downloads are stored in the ~/.cache/selenium directory.

To specify the browser and version: You can run your tests by specifying the browser with the --browser argument and, optionally, the version with the --ver argument. If the specified browser or version is not already installed, Selenium will download the appropriate browser and driver automatically and run the test against it.

Example commands:

  1. Chrome: python -m pytest -k example_form --browser Chrome

  2. Firefox: python -m pytest -k example_form --browser Firefox

  3. To specify a version: You can add the --ver argument to run the test against a specific browser version python -m pytest -k example_form --browser Chrome --ver 115.0 This will automatically download both the specified version of the browser and its corresponding webdriver if not already installed.

Note: If you already have a webdriver set up in your system's PATH and the version of that webdriver does not match the browser version you are running tests against, your test will fail. To avoid this, remove any previously set up webdrivers from your PATH before running the test to let Selenium handle the downloads.

Optional steps for integrating with third-party tools:

3. Setup for Mobile/Appium automation

a) Download and Install appium desktop app

b) Download and Install Android Studio and create an emulator

c) Install Java JDK

d) Install the appium Python client library pip install Appium-Python-Client

If your setup goes well, you should be to run a simple mobile test with this command after starting the Appium and Android emulator:

python -m pytest -k mobile_bitcoin_price --mobile_os_version $Emulator_OS_Version --device_name $Emulator_Name --app_path $App_path

Optional steps for more details on setting up appium and running tests on Android or iOS refer to below links:

4. Setup for API automation

We set API test configuration (conf/base_url_conf.py api_base_url parameter) to run tests on our hosted cars api app at https://cars-app.qxf2.com/. So you don't need any additional mandatory setup steps. You can run API tests with command "python -m pytest -k api -s"

Optional steps If you want to deploy Cars API App locally and run tests on it, you can follow below steps.

a. Get Cars API code from repo https://github.com/qxf2/cars-api using command "git clone https://github.com/qxf2/cars-api.git"

b. Install Flask using command "pip install flask"

c. Run cars-app server using command "python cars-api/cars_app.py"

d. Update API test configuration (conf/base_url_conf.py api_base_url parameter) to run tests on locally hosted app url for e.g. http://127.0.0.1:5000.

e. Run test_api_example now using command "python -m pytest -k api -s"

Optional steps for more details on setting up API and running tests refer to below links:

5. Setup for Windows automation

To automate Windows desktop applications, you need to install the Appium Server and Windows Application Driver (WinAppDriver) on the machine where your application runs.

a) Install Windows Application Driver (WinAppDriver)

Download and install WinAppDriver from the following link:

https://github.com/microsoft/WinAppDriver/releases

Make sure you choose the latest stable release (avoid pre-release versions).

b) Install Node.js and npm
(Required to install Appium) Download and install Node.js (which includes npm):

https://nodejs.org/en

During installation, ensure that the npm package option is enabled.

c) Install Appium Server

Follow the official Appium installation guide:

https://appium.io/docs/en/3.0/quickstart/install/

d) Install Appium Windows Driver

After Appium Server is installed, run the following command to install the Windows driver:

appium driver install windows

e) Verify Installation

Run the following command to verify that the Windows driver is installed:

appium driver list

You should see windows listed in the output.

f) Enable Windows Developer Mode

Before running the Windows desktop automation tests, ensure that Developer Mode is enabled on your Windows machine.

Steps:

  1. Open Settings
  2. Go to Privacy & Security
  3. Select For developers
  4. Under Use developer features, turn Developer Mode ON
  5. Confirm when prompted

This setting is enabled specifically to allow WinAppDriver to interact with and automate Windows applications.

g) Start Appium Server and Run the Test:
Open a new terminal and start the Appium server using:

appium

Once started, you should see logs indicating that Appium is running and listening at:

http://0.0.0.0:5001

If your setup is correct, you can now execute a Windows desktop automation test by running below command on another new terminal:

pytest tests/test_notepad_app.py -s -v \
  --win_app_full_path "C:\Windows\System32\notepad.exe" \
  --appium_server_address http://0.0.0.0:5001