nc-macos-tests

Automated Appium UI Tests for HiDrive Next on macOS
End-to-end tests for a better HiDrive experience

---

---

📄 Overview

This project provides a robust, automated UI test suite for the HiDrive Next macOS client.

Built using Python, Appium, and Selenium, it validates:

• Native macOS UI flows
• Web-based login/logout
• Folder navigation and selection
• UI text and version display

A sample script (test_appium_hidrivenext.py) demonstrates:

1. Launching the HiDrive Next application
2. Identifying a checkbox element via XPath and performing a click

Comes with complete setup instructions for the Appium Inspector to identify stable UI selectors.

---

📑 Table of Contents

1. Prerequisites
2. Installation
3. Maintainer Notes
4. e2e Test Execution
5. Appium Inspector Capabilities
6. Using the Appium Inspector
7. Installing Appium Inspector
8. Demo Test Execution

---

⚖️ Prerequisites

Before running the tests, ensure you have the following installed on your system:

• macOS 12.0+
• Homebrew (https://brew.sh)
• Appium Server v2.x (installed via npm install -g appium)
• Appium Inspector (for obtaining UI element locators)
• Python 3.8+
• pip (Python package manager)
• Java JDK 8+ (required by Appium)
• HiDrive Next App installed under /Applications (bundle ID: com.ionos.hidrivenext.desktopclient)

---

⬆️ Installation

# Clone the repo
$ git clone https://github.com/IONOS-Productivity/nc-macos-tests.git
$ cd nc-macos-tests

# Install dependencies
$ pip install -r requirements.txt

# Make scripts executable
$ chmod +x run_all.sh
$ chmod +x nc-macos-tests/TestplanHDNX/*.py

Start Appium server:

appium

---

📝 Maintainer Notes

📊 .env – Environment Configuration

The .env file is required to define the expected version of the HiDrive Next app for test validation.

The version is automatically read by the VersionCheck.py script using one of the following methods:

1. Environment variable HDNX_VERSION
2. Command-line argument to the script
3. .env file in the project root (recommended)

If the version is missing, the script exits with:

❌  HDNX_VERSION missing!
Place it in a .env file at the repo root, export it as an environment variable

Example .env:

HDNX_VERSION=3.13.4

View the following file VIEW-.ENV-LINK

The .env must exist at the root level. If not set, the version check test will fail.

• credentials.json stores test account login credentials (e.g., email and password) used for automated login flows. This file should never be committed to version control.

• .env is used to configure environment variables such as paths, feature flags, or debug toggles required by the test scripts. Specifically, it defines which HiDrive Next version is being tested.

• Rename credentials-example.json to credentials.json in the project root

• ⚠️ Make sure your macOS status bar has 7 visible icons, with the HiDrive app icon on the far left.

• If you have fewer icons or a different layout, adjust the pyautogui coordinates in the test scripts accordingly.

---

🌟 e2e Test Execution

Run all tests:

./run_all.sh

Run a specific test:

python nc-macos-tests/TestplanHDNX/login_logout_flow_app.py

Tests will:

• Launch HiDrive Next app
• Automate login/logout/folder operations
• Emit structured logs with visual separators

---

✅ Acceptance Criteria

• Tests complete without error
• Logs are clean, readable, and well-separated
• .env file is parsed from root
• All outputs include separators and status tags

---

🎨 Appium Inspector Capabilities

Below is the JSON representation of the desired capabilities used by the test script:

{
  "platformName": "mac",
  "appium:automationName": "mac2",
  "appium:deviceName": "Mac",
  "appium:bundleId": "com.ionos.hidrivenext.desktopclient",
  "appium:args": ["--settings"],
  "appium:noReset": true
}

---

Using the Appium Inspector

Leverage the Appium Inspector to explore the HiDrive Next UI and identify element locators (labels, XPaths, accessibility IDs):

1. Start the Appium server (if it isn’t already running):

   appium

2. Launch the Inspector:

   appium-inspector

3. Configure the connection:

   • In the Inspector window under Desired Capabilities, paste the Capabilities(JSON Representation).
   • Make sure platformName, bundleId, etc. are all correct.

4. Start a session: Click Start Session to have Appium launch the HiDrive Next app on your Mac.

5. Browse the UI hierarchy:

   • In the left-hand tree, you’ll see all UI elements.
   • Select an element to view its properties in the right-hand panel.

6. Copy a locator:

   • Under Attributes, find properties like label, name, value, xpaths, etc.
   • Right-click the desired attribute (e.g. label or xpath) and choose Copy → Copy XPath or Copy Accessibility ID.

7. Insert the locator into your test script: Paste the copied XPath or accessibility ID into your code, for example:

element = driver.find_element(By.XPATH, "//XCUIElementTypeButton[@label='My Label']")

These steps will help you generate reliable locators for your Appium tests.

---

Installing Appium Inspector

Choose one of the following installation methods:

1. Via Appium Inspector

   • Download the latest Appium Desktop release from the Appium Releases page.
   • Open the DMG and drag Appium Inspector into your Applications folder.

2. Via npm (Community Inspector)

   npm install -g appium-inspector

After installation, launch the Inspector from your Applications folder or by running:

Demo Test Execution

Run the demo test script with:

python test_appium_hidrivenext.py

The script will:

• Launch the HiDrive Next application
• Connect via Appium
• Click the checkbox located by the provided XPath
• Exit without errors

---