CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## What This Is
6 
7A Flutter demo app used as the target app for end-to-end testing of the [Maestro](https://github.com/mobile-dev-inc/maestro) mobile UI testing framework. It is not a production app — its screens exist to exercise specific Maestro features and reproduce specific bugs.
8 
9When new screens or behaviors are needed to test a Maestro feature, they are added here.
10 
11## Build Commands
12 
13```sh
14# Run the app (requires a connected device or emulator)
15flutter run
16 
17# Build Android APK
18flutter build apk
19 
20# Build iOS simulator app
21flutter build ios --simulator
22 
23# Analyze code
24flutter analyze
25```
26 
27## Maestro Flow Commands
28 
29Flows live in `.maestro/`. **Prefer the Maestro MCP** for authoring, running, and debugging flows interactively (`list_devices` → `inspect_screen` / `take_screenshot` → `run`): it returns the view hierarchy and screenshots inline, which is far more effective for iterating than parsing CLI output. Use the CLI below for scripted or CI-style runs, or when no MCP is available.
30 
31```sh
32# Run all flows
33maestro test .maestro/
34 
35# Run a single flow
36maestro test .maestro/fill_form.yaml
37 
38# Run flows with a specific tag
39maestro test --include-tags passing .maestro/
40```
41 
42**The MCP runs a *built* Maestro, not your working tree.** If you change Maestro framework code (anything outside `e2e/`) and want to validate it through the MCP against this app, the MCP will keep using the old build until Maestro is rebuilt **and the MCP is reconnected** (e.g. `/mcp reconnect maestro`). Rebuild, reconnect, then re-run. This is separate from rebuilding the demo app itself (see Build Commands) — a Dart/iOS/Android change to this app needs the app rebuilt and reinstalled on the device before the MCP will see it.
43 
44## Architecture
45 
46### Flutter App (`lib/`)
47 
48`main.dart` is the home screen with buttons navigating to each test screen. Each screen is a standalone Dart file targeting a specific testing scenario:
49 
50| File | Purpose |
51|---|---|
52| `form_screen.dart` | Login form with email/password validation |
53| `input_screen.dart` | Keyboard and text input behaviors |
54| `swiping_screen.dart` | Swipe gesture testing |
55| `nesting_screen.dart` | Deeply nested widget hierarchies |
56| `location_screen.dart` | GPS location via `geolocator`, streams position updates |
57| `sensors_screen.dart` | Device sensors (Android only) |
58| `webview.dart` | Embedded WebView via `webview_flutter` |
59| `defects_screen.dart` | Intentional UI quirks for defect regression |
60| `cropped_screenshot_screen.dart` | Screenshot cropping edge cases |
61| `notifications_permission_screen.dart` | Permission request flows |
62| `permission_check_screen.dart` | Passively displays permission status (location, all-files) via `permission_handler` — never calls `requestPermission()`, so it reflects a pre-granted state deterministically |
63| `issue_1619_repro.dart`, `issue_1677_repro.dart` | Bug reproductions |
64 
65The app reads launch arguments via `flutter_launch_arguments` (e.g., `initialCounter`, `delay`) so Maestro flows can configure app state at launch.
66 
67### Maestro Flows (`.maestro/`)
68 
69- **Root flows** (`*.yaml`): Main passing/failing test cases, tagged `passing` or used to assert expected failures.
70- **`commands/`**: Reusable Maestro command definitions (e.g., `assertVisible.yaml`, `inputText.yaml`).
71- **`android_device_configuration/`** and **`ios_device_configuration/`**: Device setup flows run before tests (disable autocorrect, set timezone, enable sensors, etc.).
72- **`web_flows/`**: Flows targeting web/WebView scenarios.
73- **`issues/`**: Flows specifically reproducing reported Maestro bugs.
74- **`experimental/`**: Unstable/in-progress flows not included in CI.
75- **`scripts/`**: JavaScript helpers used by `evalScript` commands.
76 
77`config.yaml` configures which flow directories Maestro includes when running `maestro test .maestro/`.
78 
79**Platform targeting.** Write flows to run on both Android and iOS by default. Add an `android` or `ios` tag only when the behaviour is genuinely platform-specific — a flow with no platform tag runs on every platform. Prefer keeping a single cross-platform flow over splitting into per-platform files: use `${maestro.platform == "android" ? ... : ...}` for platform-specific values, and `runFlow` with `when: platform:` to guard platform-specific steps.
80 
81### App ID
82 
83All flows target `appId: com.example.example`.
84 
85## Testing Permissions
86 
87Non-obvious gotchas when writing permission flows against this app:
88 
89- **iOS: each `permission_handler` permission must be enabled in `ios/Podfile`.** A permission's handler is compiled in only when its macro is set in `GCC_PREPROCESSOR_DEFINITIONS` (e.g. `PERMISSION_LOCATION=1`). Without it, that permission's `.status` **silently returns denied on iOS** regardless of the real authorization. Enabled today: notifications, location. After editing the Podfile, run `pod install` in `ios/` before `flutter build ios` — a Podfile edit alone won't trigger it.
90- **Android: runtime permissions must be declared in `AndroidManifest.xml`** or they can't be granted (`pm grant` throws). Declared today: INTERNET, ACCESS_FINE/COARSE_LOCATION, MANAGE_EXTERNAL_STORAGE. (So e.g. POST_NOTIFICATIONS can't be granted here.)
91- **Permission values are platform-specific.** Android uses `allow`/`deny`/`unset`; iOS `location` uses `always`/`inuse`/`never`/`unset`. iOS *validates* location values and throws on anything else; Android silently falls back to revoke for unknown/empty values. For cross-platform flows, pick per platform: `location: ${maestro.platform == "android" ? "allow" : "always"}`.
92- **`launchApp` with no `permissions:` block defaults to `all: allow`.**
93- **Observe passively.** `permission_check_screen.dart` reads status without requesting — use it to assert a pre-granted state on both platforms. Avoid `location_screen.dart` (geolocator) for that: it actively calls `requestPermission()`, popping a dialog (Android does not auto-dismiss it) and resolving position asynchronously.
94- **`MANAGE_EXTERNAL_STORAGE` is an appOps permission** on Android (special path), not a standard `pm grant` runtime permission.
95 
96## Adding New Test Screens
97 
981. Create a new `lib/<feature>_screen.dart` with a `StatefulWidget`.
992. Add a navigation button in `lib/main.dart`.
1003. Write the flow that exercises the **Maestro feature** you are testing, tagged `[passing]`. The flow is the point — the screen exists only to make that Maestro behaviour observable, not to be tested itself. Add a platform tag only if the behaviour is platform-specific (see **Platform targeting** above).
1014. For location or sensor tests, ensure relevant device configuration flows exist in the platform-specific subdirectories.
102