Metadata-Version: 2.4
Name: identifier-checker
Version: 1.1.0
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.
- 🚀 **5-Second Initial Startup Delay**: Automatically pauses for 5 seconds on initial app launch to allow splash screens, heavy SDKs, and remote data to finish loading.
- ⚡ **Ultra-Fast Missing Element Lookup**: Uses a **0.5-second** lookup timeout for missing identifiers, failing missing elements twice as fast.
- 🎯 **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. You can use either the simple list format or the automated transition format:

#### Format A: Simple List Format
```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"
    ]
  }
}
```

#### Format B: Advanced Format with Automated Screen Navigation (`transition_to_next`)
To automate screen transitions without manual terminal prompts, specify `"transition_to_next"` actions (e.g., clicking tabs/buttons, entering text, or deep links):

```json
{
  "screens": {
    "home_screen": {
      "ids": [
        "home_header_title",
        "gallery_bottom_tab",
        "quick_record_btn"
      ],
      "transition_to_next": {
        "type": "click",
        "locator_value": "gallery_bottom_tab",
        "wait_after": 2.0
      }
    },
    "gallery_screen": {
      "ids": [
        "gallery_grid_item_0",
        "gallery_filter_btn"
      ]
    }
  }
}
```

##### Supported Navigation Action Types:
- **`click`**: Clicks a button or tab (`{"type": "click", "locator_value": "button_id", "wait_after": 2.0}`)
- **`text_input`**: Enters text into input fields (`{"type": "text_input", "locator_value": "username_field", "text": "my_user"}`)
- **`deep_link`**: Navigates directly via URL scheme (`"deep_link": "myapp://settings"`)
- **`back`**: Presses the device Back button (`{"type": "back"}`)
- **`scroll_down`**: Swipes down to reveal more content (`{"type": "scroll_down"}`)
- **`wait`**: Pauses for animations to settle (`{"type": "wait", "seconds": 2.0}`)

---

### 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
```

## 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). | `Auto-resolved` |
| `--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. | `Auto-detected` |
| `--appium-url` | Appium server endpoint URL. | `http://127.0.0.1:4723` |
| `--auto-appium` | Automatically spawn and manage local Appium server if not running. | `False` |
| `--unattended` | Run in non-interactive mode executing automated transitions without pauses. | `False` (or `True` if CI=true) |
| `--auto-scroll` | Automatically scroll down to discover off-screen / lazy-loaded list items. | `False` |
| `--max-scrolls` | Maximum vertical scroll attempts per screen when `--auto-scroll` is active. | `3` |
| `--output` | Output directory OR custom `.md` / `.html` file path. | `reports` |
| `--startup-delay` | Seconds to wait on initial app startup for launch screen. | `5.0` |
| `--wait` | Seconds to wait after screen transition 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. |

---

## Guides & Documentation

- 📖 [**Local Usage, Package Commands & PyPI Deployment Guide**](RUNNING_AND_DEPLOYMENT_GUIDE.md): Complete steps for running with Python commands, CLI package commands, and releasing updates to PyPI.
- 🗺️ [**Enhancement Roadmap**](ENHANCEMENT_ROADMAP.md): Multi-pillar evolution roadmap.
