# Maestro E2E Happy Path & Extended Coverage Test Cases

This document describes the End-to-End (E2E) test cases for the KROW mobile applications (Client and Staff), implemented with [Maestro](https://maestro.mobile.dev/). It supports **ticket #572** (Happy Paths) and **ticket #636** (Extended Coverage, Negative Paths, and Structural Refactor).

## Overview

| Item | Description |
|------|-------------|
| **Framework** | Maestro |
| **Apps** | Client (`com.krowwithus.client`), Staff (`com.krowwithus.staff`) |
| **Structure** | Organized by Feature → Scenario Type (Happy Path, Smoke, Negative, Edge Cases) |
| **Total Flows** | 93 (47 Client, 46 Staff) |
| **Run locally** | See [How to run](#how-to-run) and [docs/research/maestro-test-run-instructions.md](../research/maestro-test-run-instructions.md) |

## Prerequisites

- **Maestro CLI** installed ([Install guide](../research/maestro-test-run-instructions.md#1-install-maestro-cli))
- **Firebase test phone** for Staff app (e.g. +1 555-555-1234 / OTP 123123)
- **Client & Staff APKs** built and installed on device/emulator
- **Env variables** set for credentials (never hardcode; see [Credentials](#credentials))

## Credentials

| App | Flow | Env variables |
|-----|------|----------------|
| Client | sign_in / sign_up | `TEST_CLIENT_EMAIL`, `TEST_CLIENT_PASSWORD`, `TEST_CLIENT_COMPANY` (sign_up only) |
| Staff | sign_in / sign_up | `TEST_STAFF_PHONE`, `TEST_STAFF_OTP`, `TEST_STAFF_SIGNUP_PHONE` (sign_up only) |

Example (Powershell):  
`$env:TEST_CLIENT_EMAIL="testclient@gmail.com"; $env:TEST_CLIENT_PASSWORD="testclient!"`  
`$env:TEST_STAFF_PHONE="5555551234"; $env:TEST_STAFF_OTP="123123"`

---

## Client App — Test Cases

All client flows assume the app is **not** logged in at start unless noted.

### Auth

| ID | Test | Purpose | Path |
|----|------|----------|------------|
| C-AUTH-1 | **sign_in** | Verify user can sign in | `auth/happy_path/sign_in.yaml` |
| C-AUTH-2 | **sign_up** | Verify new client registration | `auth/happy_path/sign_up.yaml` |
| C-AUTH-3 | **sign_out** | Verify user can log out | `auth/happy_path/sign_out.yaml` |
| C-AUTH-N | **sign_in_invalid** | Negative: invalid password | `auth/negative/sign_in_invalid_password.yaml` |

### Navigation (Smoke)

| ID | Test | Purpose | Path |
|----|------|----------|------------|
| C-NAV-1 | **home** | Home tab loads | `navigation/smoke/home.yaml` |
| C-NAV-2 | **orders** | Orders tab opens | `navigation/smoke/orders.yaml` |
| C-NAV-3 | **billing** | Billing tab opens | `navigation/smoke/billing.yaml` |
| C-NAV-4 | **coverage** | Coverage tab opens | `navigation/smoke/coverage.yaml` |
| C-NAV-5 | **reports** | Reports tab opens | `navigation/smoke/reports.yaml` |

### Orders

| ID | Test | Purpose | Path |
|----|------|----------|------------|
| C-ORD-1 | **view_orders** | Orders list loads | `orders/happy_path/view_orders.yaml` |
| C-ORD-2 | **create_order_one_time** | Full flow: create order | `orders/happy_path/create_order_one_time_e2e.yaml` |
| C-ORD-3 | **orders_empty_state** | Edge: verify empty tabs | `orders/edge_cases/orders_empty_state.yaml` |
| C-ORD-4 | **validation_errors** | Negative: required fields | `orders/negative/create_order_validation_errors.yaml` |

---

## Staff App — Test Cases

### Auth

| ID | Test | Purpose | Path |
|----|------|----------|------------|
| S-AUTH-1 | **sign_in** | Staff signs in with phone | `auth/happy_path/sign_in.yaml` |
| S-AUTH-2 | **sign_up** | New staff registers | `auth/happy_path/sign_up.yaml` |
| S-AUTH-3 | **sign_out** | Staff logs out | `auth/happy_path/sign_out.yaml` |

### Shifts

| ID | Test | Purpose | Path |
|----|------|----------|------------|
| S-SHF-1 | **find_shifts** | Find shifts list loads | `shifts/happy_path/find_shifts.yaml` |
| S-SHF-2 | **clock_in_e2e** | Clock in workflow | `shifts/happy_path/clock_in_e2e.yaml` |
| S-SHF-3 | **shifts_empty** | Edge: no shifts found | `shifts/edge_cases/shifts_empty_state.yaml` |

---

## How to run

### Make targets (Recommended)

| Target | Description |
|--------|-------------|
| `make test-e2e-setup` | Check Maestro CLI installation |
| `make test-e2e-client-auth` | Client: Sign In, Sign Up, Invalid Password |
| `make test-e2e-client-orders-negative`| Client: Form validation errors + empty states |
| `make test-e2e-staff-compliance-full` | Staff: Banners + Doc/Cert/Attire upload E2E |

### Windows Stability Note
If you encounter `java.io.IOException: Command failed (tcp:7001): closed`, it is due to ADB connection instability on Windows. Fix:
1.  **Restart Emulator** software.
2.  Use `--shard-split=1` (default in Makefile).
3.  Ensure timeouts are set to at least 45000ms.

## CI/CD

E2E runs in GitHub Actions: [.github/workflows/maestro-e2e.yml](../../.github/workflows/maestro-e2e.yml). 

**Trigger Change:** Automated triggers (push/PR) have been **disabled** to conserve free-tier build minutes. The workflow MUST be triggered manually via the "Actions" tab.

---

## References

- [Maestro Documentation](https://maestro.mobile.dev/)
- [Maestro Test Run Instructions](../research/maestro-test-run-instructions.md)
- [Project Makefile](../../makefiles/mobile.mk)