Metadata-Version: 2.4
Name: identifier-checker
Version: 1.0.1
Summary: Universal Mobile Runtime Identifier Verifier for Android, iOS, React Native, React Native Turbo, .NET MAUI, Capacitor, and Flutter
Author: Ayush Mishra
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: Appium-Python-Client>=3.0.0
Requires-Dist: PyYAML>=6.0

# identifier-checker

A universal, automated command-line tool for mobile QA engineers, SDETs, and test automation engineers working with any mobile application technology:
- **Native Android** (Kotlin / Java / Jetpack Compose)
- **Native iOS** (Swift / SwiftUI / UIKit)
- **React Native** (Bridged Architecture)
- **React Native Turbo** (New Architecture / Fabric)
- **.NET MAUI** (XAML / C# Multi-platform App UI)
- **Capacitor & Ionic** (HTML5 WebViews)
- **Flutter**

It verifies whether accessibility and test identifiers (`resource-id`, `content-desc`, `name`, `label`, `testID`, `AutomationProperties.AutomationId`, `id`) are present in the runtime UI hierarchy, correctly exposed in page source attributes, and queryable by live Appium element locators across your app's screens.

---

## Features

- 🌐 **Universal Framework Compatibility**: Detects test and accessibility attributes across Native Android, Native iOS, React Native, React Native Turbo Modules, .NET MAUI, Capacitor, Ionic, and Flutter.
- ⚡ **Fast Element Verification**: Uses a fast **1.0-second** element lookup timeout so missing or failed identifiers check instantly without blocking your test run.
- 🎯 **Strict Appium Locators**: Performs live element lookups using **`By.ACCESSIBILITY_ID`** and **`By.ID`** (no slow XPath overhead).
- 📱 **Screen-Wise Verification**: Group your expected identifiers screen-by-screen in a simple JSON file.
- ⏸️ **Interactive Screen Navigation**: Verifies the launch screen automatically, then prompts you to navigate to the next screen on your device/emulator before pressing `ENTER`.
- 📝 **Markdown Summary Reports**: Prints a clean terminal summary table and saves a formatted Markdown report (`id_report_<timestamp>.md` or a custom `.md` file path).
- ⚙️ **CI/CD Ready**: Exits with status code `0` when all identifiers across all screens pass, and `1` when any identifier fails or is missing.

---

## Prerequisites

Before using `identifier-checker`, make sure you have the following installed and running:

1. **Python & Package Manager**:
   - Python **3.10+**
   - `pip` (or `pipx`) installed on your system.

2. **Appium Server**:
   - Appium Server v2.x installed via Node/npm:
     ```bash
     npm install -g appium
     ```
   - Install drivers for your target platform:
     ```bash
     appium driver install uiautomator2   # For Android
     appium driver install xcuitest       # For iOS
     ```

3. **Running Appium Server**:
   - Start the Appium server in a separate terminal window before running verification:
     ```bash
     appium
     ```
     *(By default, Appium listens on `http://127.0.0.1:4723`).*

4. **Target Device**:
   - An active **Android Emulator / Real Device** (with USB debugging enabled) or **iOS Simulator**.

---

## Technology Identifier Attribute Mappings

| Tech Stack | Identifier Code Syntax | Appium Page Source Attribute | Live Lookup Locator Strategy |
|---|---|---|---|
| **Android Native** | `android:id` or `contentDescription` | `resource-id`, `content-desc` | `By.ID`, `By.ACCESSIBILITY_ID` |
| **iOS Native** | `accessibilityIdentifier` or `accessibilityLabel` | `name`, `label` | `By.ACCESSIBILITY_ID`, `By.ID` |
| **React Native / Turbo** | `testID="my_btn"` or `accessibilityLabel="my_btn"` | `resource-id` / `name` / `content-desc` | `By.ACCESSIBILITY_ID`, `By.ID` |
| **.NET MAUI** | `AutomationProperties.AutomationId="my_btn"` | `resource-id` / `name` / `content-desc` | `By.ID`, `By.ACCESSIBILITY_ID` |
| **Capacitor / Ionic** | `id="my_btn"` or `data-testid="my_btn"` | `id`, `name`, `data-testid`, `content-desc` | `By.ID`, `By.ACCESSIBILITY_ID` |
| **Flutter** | `Semantics(identifier: 'my_btn')` | `resource-id`, `content-desc`, `name` | `By.ACCESSIBILITY_ID`, `By.ID` |

---

## Step-by-Step User Guide

### Step 1: Install `identifier-checker`

Install using `python3 -m pip` (or `pipx` for global CLI tools):

```bash
python3 -m pip install identifier-checker
```

*(Or via `pipx`):*
```bash
pipx install identifier-checker
```

---

### Step 2: Create Your `expected_ids.json` File

Create a JSON file (e.g. `expected_ids.json`) listing your expected identifiers grouped by screen name:

```json
{
  "screens": {
    "home_screen": [
      "app_drawer",
      "home_core_card",
      "recent_activity_$index",
      "truvideo_sdk",
      "view_all_recent_activity"
    ],
    "all_video_requests_screen": [
      "back_button",
      "status_$index",
      "toggle_stream",
      "video_request_item_$index",
      "video_request_list_add_fab_button",
      "video_requests_id_$index",
      "video_requests_type_$index"
    ]
  }
}
```

---

### Step 3: Open Terminal and `cd` to Your JSON File Location

Open your terminal and navigate to the folder where you placed your `expected_ids.json` file:

```bash
cd /path/to/your/json/folder
```

---

### Step 4: Run the Verification Command

#### Option A: Verify an Installed Android App (via Package Name)
You only need to pass `--app-package`. Appium will automatically open your installed app's launch screen:

```bash
identifier-checker \
  --ids expected_ids.json \
  --app-package com.example.myapp
```

#### Option B: Save Report to a Custom File Path
Specify a direct Markdown file path using `--output`:

```bash
identifier-checker \
  --ids expected_ids.json \
  --app-package com.example.myapp \
  --output ~/Desktop/my_verification_report.md
```

#### Option C: Verify via APK or IPA Binary File
```bash
identifier-checker \
  --ids expected_ids.json \
  --app /path/to/your_app.apk
```

---

## Command Line Options Reference

| Argument | Description | Default |
|---|---|---|
| `--ids` | Path to JSON file containing screen-wise expected identifiers. | *Required* |
| `--app-package` | Android app package name (auto-launches installed app). | `from config` |
| `--app` | Path to APK or IPA application binary file. | `from config` |
| `--app-activity` | Android main activity name (optional). | `Auto-resolved` |
| `--platform` | Target platform (`android` or `ios`). | `android` |
| `--device-name` | Target device or emulator name. | `emulator-5554` |
| `--appium-url` | Appium server endpoint URL. | `http://127.0.0.1:4723` |
| `--output` | Output directory OR custom `.md` file path. | `reports` |
| `--wait` | Seconds to wait after app launch or screen prompt for UI to settle. | `1.0` |
| `--implicit-wait` | Timeout in seconds for element lookups. | `5.0` |
| `--no-reset` | Do not reset application state between sessions. | `True` |

---

## Exit Codes

| Exit Code | Meaning |
|---|---|
| `0` | **Success**: All expected identifiers across all screens passed exact match and live find checks. |
| `1` | **Failure**: One or more identifiers were missing, merged, failed live lookup, or a setup error occurred. |
