# Getting Started & Feature Overview
AI-powered test automation for Android, iOS, and Web — no coding required

## 1. What is QPilot?
QPilot is pCloudy's AI-powered test automation agent. It lets you author, execute, and manage test cases using plain natural language — without writing a single line of code. QPilot interprets each instruction, identifies the correct UI element, and executes the action on a real device or browser in real time.

QPilot supports three test agent types:
Android — Native and hybrid mobile app testing on real Android devices
iOS — Native and hybrid app testing on real iOS devices
Web — Desktop browser testing on Chrome, Firefox, and more

## Why QPilot?

| Capability | How QPilot Delivers It |
| --- | --- |
| Natural Language Authoring | Write test steps in plain English — QPilot translates to executable actions |
| No Coding Required | Zero framework knowledge needed. Any QA engineer or PM can author tests. |
| Real Devices & Browsers | Tests run on real pCloudy devices, not emulators — true production fidelity |
| AI Element Detection | QPilot automatically generates XPath locators for every action |
| Inline API Testing | Insert backend API calls inline within your UI test flow |
| Dynamic Test Data | JSON variables with `{{key}}` syntax for parameterised, reusable tests |

## 2. Creating a Project, Folder, and Test Case
Before you can author test steps, set up your workspace in the following order.

### Step 1 — Create a Project
- A Project is the top-level container for all test cases belonging to a single product or client.
- From the Dashboard, click All Projects
- Click the New Project icon from the toolbar
- Give your project a meaningful name that reflects the product or team
- Choose Private Project (visible only to you) or Team Project (shared with your workspace)

Example project names: ShopEasy, BankingApp, MyRetailClient

### Step 2 — Create a Folder
- Folders organise your test cases by platform or feature area within a project.
- Select your newly created project from the left panel
- Click the New Folder icon
- Name the folder to reflect the platform or feature being tested

Example folder names: Android, iOS, Web, Checkout, Login, Registration

### Step 3 — Create a Test Case
- Select the folder you just created
- Click New Test Case
- Select the agent: Android, iOS, or Web
- Enter a Test Case Name that clearly describes what the test covers
- Optionally add a Test Description by clicking + Add Test Description

Example names: Login_Valid_User, Add_to_Cart_Flow, Registration_New_User, Search_Product

## 3. Configuring Application Details

## Mobile (Android & iOS)

| Field | Description | Example |
| --- | --- | --- |
| Application Name | Select uploaded APK or IPA from the dropdown | ShopEasy_v2.apk |
| Package Name | Unique app identifier — from AndroidManifest.xml | com.shopeasy.android |
| Package Activity | Activity that launches the app | com.shopeasy.android.ui.SplashActivity |

> **Tip:** Your development team or the app's AndroidManifest.xml file is the best source for Package Name and Package Activity values.

## Web
Provide the URL of the web application you want to test.
Example: https://staging.shopeasy.com, https://app.myretailclient.com/login

## 4. Selecting a Device
Under Available Device, browse by manufacturer (Google, Samsung, OnePlus, etc.) or search by OS version or Chrome version.
- A green dot next to a device indicates it is online and available
- Once selected, the footer bar confirms: Launching [App] on [Device]

Click Save & Go to Playground to begin.

## 5. The Playground
The Playground is your interactive authoring environment. It consists of three panels:

| Panel | Purpose |
| --- | --- |
| Left Panel | Live list of test steps with their real-time execution status |
| Right Panel | Real-time device or browser mirror showing the app as steps execute |
| Input Bar (bottom) | Type your next step in natural language, or type / to open the full command menu |

## Writing Test Steps
Enter each instruction in plain English. QPilot translates it into an executable automation action with an XPath locator and a reasoning explanation.
You can enter a single step at a time or paste multiple steps at once — QPilot will queue and execute them sequentially.

## Example steps — Mobile:
- Click the Get Started button
- Enter `{{username}}` in the email input field
- Enter `{{password}}` in the password field
- Click the Login button
- Scroll down
- Click the first product in the list
- Click Add to cart
- Take a screenshot of the screen

## Example steps — Web:
- Click the Sign In link in the top navigation
- Enter `{{E1}}` in the email field
- Enter `{{P1}}` in the password field
- Click the Submit button
- Assert that the page heading says Welcome Back
- Take a screenshot of the current page

> **Tip:** Be specific about the element. Instead of "Click the button", say "Click the Add to Wishlist button on the product detail page."

## 6. Step Status Indicators

| Icon | Status | Meaning |
| --- | --- | --- |
| ✅ | Passed | Step executed successfully |
| 🟡 | Queued | Step is pending execution |
| ⊖ | Skipped | Step was bypassed |
| 🟠 | Aborted | Step execution was interrupted |
| 🔴 | Failed | Step did not execute as expected |

## 7. Test Data — Using Variables
QPilot supports dynamic test data via JSON and double-curly-bracket syntax.

## Defining Test Data
Test data is stored in JSON format and attached to your test case:

```json
{
  "username": "john.doe@email.com",
  "password": "Test@1234",
  "phone": "9876543210",
  "name": "John Doe",
  "zipcode": "560001"
}
```

## Using Variables in Steps
Reference any key from your JSON using `{{key_name}}` directly in your step description:

- Enter `{{username}}` in the email field
- Enter `{{phone}}` in the Mobile Number field
- Enter `{{name}}` in the Full Name field
- Enter `{{zipcode}}` in the postal code field

> **Tip:** Ideal for parameterised tests such as login flows, registration forms, and search queries where input data changes between runs.

## 8. Assertions & Validations
When you write validation steps, QPilot automatically creates local variables to store captured values for assertion.

- Validate if 'Order Confirmed' is present on the screen
- Assert that the cart item count shows 1
- Check if the error message 'Invalid email address' is displayed
- Verify the user profile name reads John Doe

> **Info:** Assertions fail the test immediately upon a mismatch by default.

## 9. API Steps
You can insert API calls inline within your test flow using the Add API Step option.

| Field | Description |
| --- | --- |
| Method | HTTP method: GET, POST, PUT, DELETE, etc. |
| API URL | Full endpoint URL (e.g., https://api.shopeasy.com/v1/users) |
| Params | Key-value query parameters |
| Authorization | Auth token or credentials |
| Headers | Custom HTTP headers |
| Body | Request payload for POST/PUT calls |

Use case: After completing a registration flow through the UI, call `GET /v1/users/{{username}}` to confirm the account was created on the backend before proceeding with further UI steps.

## 10. Editing a Test Case

## Edit / Retry an Individual Step
- Edit step name — Click the pencil icon on the right of any step to rename it inline
- Edit XPath locator — Expand a step to view its xpath value and manually override the AI-generated locator if needed
- Retry a single step — Click the retry (↺) icon to re-execute just that one step without rerunning the entire test

> **Tip:** If a step fails because the element was not yet visible, add a 'Wait for 3 seconds' step before it and then retry.

## Add / Delete Steps (Edit Mode)
Click the Edit button (pencil icon, top right of the Playground) to enter full Edit Mode. The status banner will change to DRAFTING.

- Add a step — Click + Add Step between any existing steps to insert a new instruction at that position
- Delete a step — Click the red trash icon on the right of any step to remove it permanently

At the bottom of the Edit view, there is a Restart test checkbox:

- When unchecked, clicking Save preserves the current execution results and only saves structural changes
- When checked, clicking Save will regenerate and re-execute all steps from the beginning

> **Tip:** If you add or remove a step that changes app state for downstream steps, always enable Restart test before saving.

## 11. Finishing Your Test Case
- Click the Finish button (top right, green)
- QPilot saves the test case and returns you to the Summary view

## 12. Post-Generation Actions (Summary View)

| Button / Option | Action |
| --- | --- |
| Run | Execute the test case immediately |
| View Live Session | Watch the current execution in real time on the device or browser mirror |
| Duplicate | Clone the test case to create a variant or reuse the flow with different test data |
| Open in Playground | Re-enter the authoring environment to add or modify steps |
| Edit (pencil icon) | Edit app configuration — APK/URL, Package Name, Package Activity, or test data |
| Runs tab | Full execution history with timestamps, pass/fail counts, and drill-down into run results |