Updated on 2026-08-14

.claude/skills/write-ui-test/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: write-ui-test
+description: Write a Kaspresso/Compose instrumentation UI test for the Tangem Android app following project conventions — test class shape, page-object locations, Allure step naming, WireMock scenario setup, synchronization, and meaningful assertions. Covers known Compose traps (PullToRefreshBox swipe, TangemHoldToConfirmButton, Decompose lifecycle, hot-wallet access code) and the build/run/debug flow. Use when the user asks to write, add, port, or fix an instrumentation / androidTest / UI test, a page object, or a test scenario ("напиши UI-тест", "добавь инструментальный тест", "напиши тест в androidTest", "page object", "автотест на экран").
+allowed-tools: Read, Grep, Glob, Bash, Edit, Write, Agent
+argument-hint: [screen/flow or TC# to cover, e.g. "TangemPay freeze card"]
+---
+
+Write an instrumentation (androidTest) UI test for the Tangem Android app. These conventions are
+enforced by reviewers (tnagmetulla, dpodoynikov) — applying them up front skips a review round.
+
+This is an **interactive** skill: if scope is ambiguous (which screen, which flow, what the final
+assertion should verify), ask before writing. Do not invent UI text or test tags — read the real
+production source and reuse existing patterns.
+
+## When to use
+
+Use for instrumented UI tests under `app/src/androidTest/` (Kaspresso + Kakao-Compose), page objects,
+and test scenarios. **Not** for JVM/Robolectric unit tests (`testDebugUnitTest`) — those follow a
+different setup.
+
+## Workflow
+
+1. **Clarify scope.** Which screen/flow, which Allure TC#, and what the *final assertion* verifies.
+   Ask if any of these is unclear.
+2. **Find an existing sibling test to mirror.** Grep `app/src/androidTest/` for a test on a similar
+   screen (e.g. `SendViaSwapTest`). Match its structure rather than inventing one. Read the real
+   production composable to get the actual `testTag`s and string resources — never guess UI text.
+3. **Locate / extend page objects** in `com/tangem/screens/` (see Locations). Add new ones there,
+   never inside the scenario or test file.
+4. **Set up WireMock scenarios** in the *test body* if the flow depends on backend state
+   (see `reference/running-and-debugging.md`).
+5. **Write the test** per Conventions below.
+6. **Build BOTH APKs, install, run, and classify the result** correctly — Allure post-run hook
+   failures are not test failures (see `reference/running-and-debugging.md`).
+
+## Porting a test from iOS
+
+When the user asks to **port** an iOS test to Android:
+
+- **Default to the sibling iOS repo `../tangem-app-ios/`** (next to `tangem-app-android`). If that path
+  doesn't exist, **ask the user** where the iOS repo is — don't guess.
+- iOS UI tests live under `TangemUITests/`; look there for the source test, its page objects
+  (`*Screen`), and accessibility identifiers (`*AccessibilityIdentifiers`).
+- Port the *intent and steps*, not the API. Map the iOS stack to the Android one:
+  XCUITest/accessibility identifiers → Compose `testTag`; iOS `*Screen` page objects → Kotlin page
+  objects in `com/tangem/screens/`; XCTest assertions → Kaspresso/Truth assertions. Re-derive the real
+  Android `testTag`s and string resources from production source — never reuse iOS identifier strings.
+- The WireMock scenarios are usually shared across platforms, but the branch may differ
+  (see `reference/running-and-debugging.md`).
+
+## Conventions (must-follow)
+
+### Test class shape
+
+- **Scenario state setup goes in the test body**, not inside the open-the-feature helper. Each test
+  starts with explicit `step("Set WireMock scenario '$name' to '$state'") { setWireMockScenarioState(name, state) }`
+  calls, then calls a thin helper (e.g. `openTangemPay()`) that only opens the screen. Mirror the
+  `SendViaSwapTest` pattern.
+- **Open-the-feature helpers stay thin** — no scenarios-as-parameters, no scenario juggling inside.
+- **Every scenario name + state is a `val`** at the top of the test method. Reviewers reject magic
+  strings inside `step(...)`.
+- **Each click is its own** `step("Click on '$x' button")`. Combining clicks into one step hides which
+  click failed in the Allure report.
+- **Step naming**: `Click on 'X' button` (not "Tap X"); `Assert <thing> is displayed` (not "Check X
+  visible"). Keep it consistent with the existing suite.
+- **No conditional `if (foo.isDisplayedSafely()) foo.performClick()`** for elements that are
+  deterministically present after `pm clear` — the `if` is dead code. Use a straight `performClick()`.
+
+### Locations
+
+| What | Where |
+|------|-------|
+| Page objects | `app/src/androidTest/kotlin/com/tangem/screens/…` — **always** |
+| Common test helpers | `app/src/androidTest/kotlin/com/tangem/common/utils/` |
+| Feature scenarios | `app/src/androidTest/kotlin/com/tangem/scenarios/` |
+| Cross-feature helper (e.g. `confirmSwapByHolding`) | the **feature-of-origin** scenarios file (e.g. `SwapScenarios.kt`), not the consumer's |
+
+Scenario files orchestrate flows; they must not define page objects or duplicate generic helpers.
+
+### Strings
+
+- **No hardcoded UI text** in matchers. Use `getResourceString(R.string.foo)` from
+  `com.tangem.core.res.R` or `com.tangem.core.ui.R`. The Detekt rule `UnsafeStringResourceUsage`
+  enforces this for production code; reviewers extend it to test code informally.
+
+### Assertions
+
+- **Never** use Kotlin's built-in `assert(...)` — Android instrumentation runs don't enable JVM
+  assertions, so `assert(false)` is a silent no-op. Use Truth / JUnit / Kaspresso / Kakao assertions.
+- **Clipboard checks**: `assertClipboardTextEquals(expected, context)` from `common/utils/ClipboardUtils.kt`.
+  Read displayed text via `KNode.extractText()` first if you need to compare against UI state.
+- **Every test ends with a meaningful assertion**, not just an action. A test whose last step is
+  "Click Submit" without verifying the result gets rejected.
+
+### Waits and synchronization
+
+- **Manual polls are banned** (`onAllNodes(matcher).fetchSemanticsNodes().isNotEmpty()` in a loop). Use:
+  - `composeTestRule.waitUntilAtLeastOneExists(matcher, timeoutMillis)` — wait for one thing to appear.
+  - `composeTestRule.waitUntil(timeout) { runCatching { someAssertion() }.isSuccess }` — wait until an
+    action no longer throws.
+  - `composeTestRule.waitUntil(timeout) { matcherA exists || matcherB exists }` — the either/or case.
+- **`flakySafely(timeout)`** (Kaspresso) is reachable only from `TestCase` subclasses, NOT from
+  extension functions on `BaseTestCase`. In extension code use the `waitUntil` variants above.
+
+### Comment hygiene
+
+This repo enforces "no comments unless WHY is non-obvious", in test code too. One line max, WHY-only —
+encode a hidden constraint, not what the code does. Example that earns its keep:
+`// Create+confirm screens share ACCESS_CODE_INPUT — gate on confirm-screen title.`
+Delete anything explaining WHAT a step does.
+
+## Reference docs
+
+- **`reference/compose-traps.md`** — read when the screen uses `PullToRefreshBox`,
+  `TangemHoldToConfirmButton`, a Decompose model that fetches in `init {}`, or a hot-wallet import with
+  an access code. These have silent failure modes that look like passing tests.
+- **`reference/running-and-debugging.md`** — read when building, installing, running a single test,
+  interpreting CLI/Allure output, using `@Ignore`, or driving WireMock scenarios.

.claude/skills/write-ui-test/reference/compose-traps.md

@@ -0,0 +1,66 @@
+# Compose UI test traps
+
+Each of these has a **silent** failure mode: the gesture/action appears to run, the test stays green
+(or fails for the wrong reason), but the intended behavior never fired. Diagnose with logcat network
+traces or a semantics-tree snapshot, not by visually watching the swipe.
+
+## Material3 `PullToRefreshBox` + UiAutomator swipe = silent no-op
+
+`androidx.compose.material3.pulltorefresh.PullToRefreshBox` reacts to overscroll deltas via Compose's
+`NestedScrollConnection` from the inner `LazyColumn`. UiAutomator's `device.swipe(x1,y1,x2,y2,steps)`
+dispatches platform `MotionEvent`s; the `LazyColumn` receives them as an ordinary scroll, never
+produces overscroll, and `onRefresh` never fires — regardless of `steps=30` (fling) or `steps=1000`
+(slow drag). Confirmed by `NetworkLogs`: zero refresh calls after the UiAutomator swipe, vs. one
+immediate call via the Compose Test API.
+
+**Use the Compose Test API:**
+
+```kotlin
+composeTestRule.onNode(hasTestTag(SOME_TAG_INSIDE_THE_BOX))
+    .performTouchInput {
+        swipeDown(startY = 0f, endY = visibleSize.height.toFloat() * 6f, durationMillis = 800)
+    }
+```
+
+The shared `pullToRefresh()` in `common/extensions/UiDeviceExt.kt` is UiAutomator-based and works for
+*some* screens (a different refresh container), but **not** for Material3 `PullToRefreshBox`. When
+porting a test, verify with a logcat network trace, not visual inspection.
+
+## `TangemHoldToConfirmButton` semantics are minimal
+
+The component exposes ONLY `TestTag`, `IsContainer`, `Shape` in Compose semantics — no `Disabled`,
+`Role`, or `OnClick`. `assertIsEnabled()` / `assertHasClickAction()` are useless on it.
+
+`Modifier.holdToConfirmGestures(enabled, ...)` early-returns from `pointerInput` when `enabled=false`,
+so the hold gesture is silently swallowed: the button looks fine, the user holds, nothing happens,
+`onConfirm` never fires.
+
+**Diagnose "silently disabled" from a test:**
+1. Snapshot the Compose semantics tree before the hold.
+2. Perform the hold: `performTouchInput { longClick(durationMillis = HOLD_DURATION_MS) }`.
+3. Snapshot again — byte-identical trees mean `onConfirm` didn't run.
+4. Or check WireMock request stats for the downstream API call expected after `onConfirm`.
+
+## Decompose model lifecycle vs. data refresh
+
+Models (e.g. `TangemPayDetailsModel`) call data fetches from `init {}`, NOT on `ON_RESUME`. Returning
+to a screen via `router::pop` does NOT re-fetch. A test that switches WireMock scenarios between an
+action and the assertion MUST explicitly trigger a refresh on the now-frontmost screen — otherwise the
+stale in-memory data wins.
+
+## Hot wallet imports with access code
+
+- `openMainScreenWithExistingHotWallet(seedPhrase, accessCode: String = "")` in `BaseScenarios.kt`
+  handles both flows via the optional param — DO NOT introduce a parallel `importHotWalletWithAccessCode`.
+- Access-code **create** and **confirm** screens share the same `ACCESS_CODE_INPUT` testTag. Gate the
+  confirm-screen action on the confirm-screen's unique title:
+
+  ```kotlin
+  composeTestRule.waitUntilAtLeastOneExists(
+      hasText(getResourceString(CoreUiR.string.access_code_confirm_title)),
+      timeoutMillis = WAIT_UNTIL_TIMEOUT_LONG,
+  )
+  ```
+
+- Tangem Pay eligibility (`PaeraCustomer`) rejects hot wallets with `authType=NoPassword` — those tests
+  must use the access-code path.

.claude/skills/write-ui-test/reference/running-and-debugging.md

@@ -0,0 +1,88 @@
+# Building, running, and debugging instrumentation tests
+
+## Both APKs matter
+
+Instrumentation tests need TWO APKs:
+
+- `:app:assembleGoogleMocked` → `app-google-mocked.apk` — production code under test
+- `:app:assembleGoogleMockedAndroidTest` → `app-google-mocked-androidTest.apk` — the test code
+
+If you change production code and rebuild only the test APK, **the installed main APK stays old** and
+your fix doesn't take effect. Symptom: "the fix doesn't help" — except it does, you just ran the
+unfixed build.
+
+```bash
+# Build both
+./gradlew :app:assembleGoogleMocked :app:assembleGoogleMockedAndroidTest
+# Install each
+adb install -r -t <path-to-app-google-mocked.apk>
+adb install -r -t <path-to-app-google-mocked-androidTest.apk>
+```
+
+## Run a single test (manual)
+
+```bash
+adb shell pm clear com.tangem.wallet.mocked
+curl -X POST http://localhost:8081/__admin/scenarios/reset
+adb shell am instrument -w \
+  -e class "com.tangem.tests.tangempay.TangemPayTest#freezeUnfreezeCard_TogglesCardState" \
+  com.tangem.wallet.mocked.test/com.tangem.common.HiltTestRunner
+```
+
+## Classify the result — Allure noise vs. real failure
+
+After `pm clear`, `/data/user/0/<pkg>/files/original_screenshots` doesn't exist →
+`AllureResultsHack.testRunFinished` throws `NoSuchFileException` → reported as
+`Tests run: 1, Failures: 1` with a stack trace starting at `AllureResultsHack`. **This is a post-run
+hook failure, NOT a test logic failure.**
+
+Distinguish:
+- First stack frame is `AllureResultsHack.testRunFinished` → infra hook noise; ignore it.
+- Kaspresso step logs show all `SUCCEED` for steps 1..N → the test passed.
+- A REAL failure shows `java.lang.AssertionError` inside the test's own classes
+  (e.g. `at com.tangem.tests.X.foo$lambda…`). When auto-classifying CLI output, key off the presence
+  of `java.lang.AssertionError` vs. only `original_screenshots`.
+
+## `@Ignore` on instrumentation tests
+
+- Pattern: `@Ignore("https://tangem.atlassian.net/browse/AND-XXXXX")` above `@Test`.
+- When ignored, `am instrument -e class …` reports `OK (0 tests)` with `Tests run: 0`
+  (NOT `Skipped: 1`). Auto-detection should match the zero-test count.
+
+## WireMock cheatsheet
+
+Local override is detected; otherwise hits remote. Default local port: `8081`.
+
+```bash
+# Set a scenario state — PUT, not POST
+curl -X PUT http://localhost:8081/__admin/scenarios/<name>/state \
+     -H "Content-Type: application/json" -d '{"state":"<state>"}'
+
+# Reset all scenarios
+curl -X POST http://localhost:8081/__admin/scenarios/reset
+
+# Inspect
+curl http://localhost:8081/__admin/mappings | jq
+curl http://localhost:8081/__admin/scenarios | jq '.scenarios[] | {name, state}'
+```
+
+- Mocks repo: default to the sibling directory `../tangem-api-mocks/` (i.e. next to
+  `tangem-app-android`). If that path doesn't exist, **ask the user** where the mocks repo is rather
+  than guessing.
+- The repo is **branch-per-suite** — dozens of feature branches (e.g. `send-via-swap-p1`,
+  `account-creation`, `swap-express-mocks`, `android-tangem-pay-mocks`). There is no universal
+  default branch; check out the one the suite under test expects. If it's unclear which branch holds
+  the mappings for your flow, ask the user. Mappings live under `mocks/mappings/`, response bodies
+  under `mocks/__files/`.
+- **State transitions are atomic per `requiredScenarioState`.** If a scenario defines an `AfterDeposit`
+  mapping for `/customer/balance` but not `/customer/me`, a request to `/customer/me` after switching
+  to `AfterDeposit` falls through. Check *both* endpoints when an "after" assertion fails.
+
+## Misc
+
+- `./gradlew unitTest` aggregates all debug/googleDebug + JVM-module tests — faster than per-module
+  tasks for verifying a broad change (but it's for *unit* tests, not instrumentation).
+- Detekt config lives in the `tangem-android-tools` git submodule — look there before assuming a local
+  `.detekt.yml`.
+- Path discipline: stay in `/Users/maxibello/dev/tangem-app-android`; `cd` into the mocks repo only when
+  needed and prefer absolute paths (the shell session resets cwd).