diff --git a/flows/core_app_settings.yaml b/flows/core_app_settings.yaml new file mode 100644 index 0000000000..af06964bca --- /dev/null +++ b/flows/core_app_settings.yaml @@ -0,0 +1,3 @@ +appId: ${APPID} +--- +- runFlow: appsettings.yaml diff --git a/flows/core_key_management.yaml b/flows/core_key_management.yaml new file mode 100644 index 0000000000..b49acc84e5 --- /dev/null +++ b/flows/core_key_management.yaml @@ -0,0 +1,4 @@ +appId: ${APPID} +--- +- runFlow: walletSetting.yaml +- runFlow: healthCheckKey.yaml diff --git a/flows/core_onboarding_setup.yaml b/flows/core_onboarding_setup.yaml new file mode 100644 index 0000000000..178eb7787a --- /dev/null +++ b/flows/core_onboarding_setup.yaml @@ -0,0 +1,5 @@ +appId: ${APPID} +--- +- runFlow: newapp.yaml +- runFlow: addwallet.yaml +- runFlow: addNewKey.yaml diff --git a/flows/core_receive_send.yaml b/flows/core_receive_send.yaml new file mode 100644 index 0000000000..5278cf8605 --- /dev/null +++ b/flows/core_receive_send.yaml @@ -0,0 +1,4 @@ +appId: ${APPID} +--- +- runFlow: receive.yaml +- runFlow: send.yaml diff --git a/flows/core_regression.yaml b/flows/core_regression.yaml new file mode 100644 index 0000000000..97df39a163 --- /dev/null +++ b/flows/core_regression.yaml @@ -0,0 +1,7 @@ +appId: ${APPID} +--- +- runFlow: core_onboarding_setup.yaml +- runFlow: core_wallet_viewing.yaml +- runFlow: core_app_settings.yaml +- runFlow: core_key_management.yaml +- runFlow: core_receive_send.yaml diff --git a/flows/core_wallet_viewing.yaml b/flows/core_wallet_viewing.yaml new file mode 100644 index 0000000000..3afdc99f58 --- /dev/null +++ b/flows/core_wallet_viewing.yaml @@ -0,0 +1,3 @@ +appId: ${APPID} +--- +- runFlow: viewwallet.yaml diff --git a/openspec/changes/archive/2026-05-08-add-maestro-core-journey-flows/.openspec.yaml b/openspec/changes/archive/2026-05-08-add-maestro-core-journey-flows/.openspec.yaml new file mode 100644 index 0000000000..054b8c0135 --- /dev/null +++ b/openspec/changes/archive/2026-05-08-add-maestro-core-journey-flows/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-05-08 diff --git a/openspec/changes/archive/2026-05-08-add-maestro-core-journey-flows/design.md b/openspec/changes/archive/2026-05-08-add-maestro-core-journey-flows/design.md new file mode 100644 index 0000000000..5deaf55633 --- /dev/null +++ b/openspec/changes/archive/2026-05-08-add-maestro-core-journey-flows/design.md @@ -0,0 +1,72 @@ +## Context + +Bitcoin Keeper already has individual Maestro flows in `flows/`, but there is no consolidated, PR-friendly core journey suite that teams can run for quick regression confidence. Existing flows also vary in scope, so adding a thin composition layer gives broad coverage without changing app code or existing selectors. + +Constraints: +- Keep changes limited to Maestro YAML assets under `flows/`. +- Reuse existing IDs/text assertions to avoid brittle selector drift. +- Preserve current app behavior for both mainnet/testnet UI states. + +Stakeholders: +- Mobile engineers validating PRs. +- QA/release owners running fast smoke/regression checks. + +## Goals / Non-Goals + +**Goals:** +- Add a small set of journey-oriented Maestro flow files that cover onboarding/setup, wallet viewing, receive, send, app settings, and key-management. +- Keep flow style consistent (`appId` header, `runFlow` composition, existing assertion patterns). +- Provide one top-level composed regression flow for easy execution. + +**Non-Goals:** +- Changing React Native app code, Redux store, sagas, Realm models, or navigation logic. +- Introducing new selectors or refactoring existing legacy flow files extensively. +- Adding hardware-device-in-the-loop automation. + +## Decisions + +1. **Use composition over rewriting existing flows** + - Decision: Create new wrapper flows that call stable existing flows with `runFlow`. + - Rationale: Minimal/surgical change, low maintenance, fast to review. + - Alternative considered: Rewrite existing flows into a new unified monolith; rejected due to higher risk and selector churn. + +2. **Add a single top-level regression entrypoint** + - Decision: Add one composed flow that runs all new journey wrappers in sequence. + - Rationale: Gives a predictable CI/manual command target and maps directly to required coverage journeys. + - Alternative considered: Keep only independent journey files; rejected because orchestration burden shifts to callers. + +3. **No app logic/state changes** + - Decision: Limit implementation strictly to `flows/` YAML files. + - Rationale: This effort is test coverage only. + - Redux slices/sagas involved: none. + - Realm/MMKV changes: none. + - Migration requirement (`src/store/migrations.ts`): none. + +4. **PSBT/hardware interaction treatment** + - Decision: Reuse existing send/key-management flows that already traverse UI steps tied to transaction signing/key surfaces without adding new signer protocol logic. + - Data flow note: tests remain UI-driven and rely on existing in-app send/key pathways; no direct PSBT/hardware protocol manipulation is introduced. + +Affected files (planned): +- `flows/core_onboarding_setup.yaml` (new) +- `flows/core_wallet_viewing.yaml` (new) +- `flows/core_receive_send.yaml` (new) +- `flows/core_app_settings.yaml` (new) +- `flows/core_key_management.yaml` (new) +- `flows/core_regression.yaml` (new) + +## Risks / Trade-offs + +- **[Risk] Existing legacy flow instability can propagate into composed suite** → Mitigation: Keep wrappers thin and reuse already-used flows with stable IDs/text assertions. +- **[Risk] Send flow depends on wallet/network state** → Mitigation: Keep coverage practical by composing current branch flows rather than introducing new brittle assertions. +- **[Trade-off] Broad but shallow journey coverage** → Mitigation: This suite is explicitly smoke/regression; deeper edge-case coverage can be added in separate targeted flows. + +## Migration Plan + +1. Add new composed Maestro YAML files under `flows/`. +2. Validate YAML syntax/consistency with available local checks. +3. Run selected Maestro flow command(s) if environment supports execution. +4. No runtime migration, rollout, or rollback steps needed because app code is unchanged. + +## Open Questions + +- None blocking for this change. diff --git a/openspec/changes/archive/2026-05-08-add-maestro-core-journey-flows/proposal.md b/openspec/changes/archive/2026-05-08-add-maestro-core-journey-flows/proposal.md new file mode 100644 index 0000000000..b5de867dc0 --- /dev/null +++ b/openspec/changes/archive/2026-05-08-add-maestro-core-journey-flows/proposal.md @@ -0,0 +1,39 @@ +## Why + +Bitcoin Keeper currently lacks broad Maestro journey coverage for critical app paths, which increases regression risk for release candidates. We need a small, maintainable set of flow tests that cover core user navigation and key wallet actions end-to-end. + +## What Changes + +- Add new Maestro flow YAMLs under `flows/` for core journeys: onboarding/setup, wallet viewing, receive, send, settings, and key-management. +- Add a composed smoke/regression flow that runs these journey flows in sequence using `runFlow`. +- Keep selectors and assertions aligned with existing in-repo Maestro conventions (screen IDs/text assertions and `appId` header usage). +- Limit scope to flow coverage additions only; no production app logic changes. +- Environment impact: applies to both mainnet and testnet UI journeys (flow-level navigation coverage is network-agnostic unless explicitly gated by screen text). +- Hardware signer compatibility impact: no protocol behavior changes; key-management checks validate UI accessibility only and do not alter PSBT/hardware integrations. +- Subscription tier gating impact: no subscription logic changes; flows should tolerate tier-gated surfaces by asserting stable, non-premium entry points where possible. + +## Capabilities + +### New Capabilities +- `maestro-core-journey-flows`: Defines baseline Maestro test coverage for essential Bitcoin Keeper journeys through composable YAML flows. + +### Modified Capabilities +- None. + +## Impact + +- Affected area: `flows/` Maestro test assets only. +- APIs/dependencies: no new runtime dependencies, no API contract changes. +- Systems: improves CI/manual QA confidence for onboarding, wallet navigation, send/receive, settings, and key-management paths. + +## Non-goals + +- Changing app feature behavior, navigation structure, or component IDs. +- Adding deep negative-path matrixes for every device/network scenario. +- Automating external hardware signer interactions beyond existing UI-access checks. + +## Security & Privacy Impact + +- No new key material is created, exported, or stored by this change. +- No new network calls are introduced; flows only exercise existing UI paths. +- No storage schema or secret-handling logic is modified. diff --git a/openspec/changes/archive/2026-05-08-add-maestro-core-journey-flows/specs/maestro-core-journey-flows/spec.md b/openspec/changes/archive/2026-05-08-add-maestro-core-journey-flows/specs/maestro-core-journey-flows/spec.md new file mode 100644 index 0000000000..41e18f6847 --- /dev/null +++ b/openspec/changes/archive/2026-05-08-add-maestro-core-journey-flows/specs/maestro-core-journey-flows/spec.md @@ -0,0 +1,38 @@ +## ADDED Requirements + +### Requirement: Core journey suite entrypoint +The system SHALL provide a Maestro flow entrypoint that executes core user journeys for onboarding/setup, wallet viewing, receive, send, app settings, and key-management. + +#### Scenario: Full core regression composition +- **GIVEN** Maestro is configured with `${APPID}` and a valid test account context for Wallet and Vault screens +- **WHEN** the tester runs the core regression flow entrypoint +- **THEN** the flow MUST invoke composed subflows for onboarding/setup, wallet viewing, receive/send, app settings, and key-management in a deterministic order + +### Requirement: Journey flows SHALL align with existing selectors and assertions +Each new journey flow MUST reuse established IDs/text assertions from existing Bitcoin Keeper Maestro flows to reduce selector drift and maintenance risk. + +#### Scenario: Selector compatibility with current branch conventions +- **GIVEN** existing Wallet and Signer UI elements expose IDs/text used in current `flows/*.yaml` +- **WHEN** new journey wrapper flows are added +- **THEN** the wrappers MUST reference existing flow files and retain existing assertion behavior instead of introducing unverified selectors + +### Requirement: Receive and send journey coverage +The suite SHALL cover receive and send pathways for a Wallet, including transition into send amount/fee review surfaces that operate on satoshi-backed wallet balances (display format may be BTC). + +#### Scenario: Wallet receive and send composition +- **GIVEN** a Wallet with spendable UTXO state and at least 1100 satoshis available for test sending +- **WHEN** the receive/send journey flow runs +- **THEN** it MUST execute receive and send subflows and reach send confirmation/broadcast UI outcomes without changing Signer protocol behavior + +#### Scenario: Network-dependent send handling +- **GIVEN** Electrum connectivity is offline or unstable during send journey execution +- **WHEN** the receive/send journey flow invokes the send subflow +- **THEN** the flow MUST fail at existing in-app send/network checks rather than bypassing wallet/network validation + +### Requirement: Settings and key-management journey coverage +The suite SHALL include app settings and key-management pathways relevant to Wallet, Vault, and Signer maintenance surfaces. + +#### Scenario: Settings and key surfaces are exercised +- **GIVEN** the test account can access settings and manage keys from current app navigation +- **WHEN** the settings and key-management journey flows run +- **THEN** the composed suite MUST traverse existing settings and key-management subflows and verify expected navigation/assertion checkpoints diff --git a/openspec/changes/archive/2026-05-08-add-maestro-core-journey-flows/tasks.md b/openspec/changes/archive/2026-05-08-add-maestro-core-journey-flows/tasks.md new file mode 100644 index 0000000000..4c31aeccc8 --- /dev/null +++ b/openspec/changes/archive/2026-05-08-add-maestro-core-journey-flows/tasks.md @@ -0,0 +1,26 @@ +## 1. UI Components (Maestro Flow Assets) + +- [x] 1.1 Add `flows/core_onboarding_setup.yaml` to compose onboarding/setup coverage using existing base flows. +- [x] 1.2 Add `flows/core_wallet_viewing.yaml` to compose wallet viewing coverage using existing wallet detail/view flows. +- [x] 1.3 Add `flows/core_receive_send.yaml` to compose receive + send wallet journey coverage. +- [x] 1.4 Add `flows/core_app_settings.yaml` to compose app settings journey coverage. +- [x] 1.5 Add `flows/core_key_management.yaml` to compose key-management journey coverage. +- [x] 1.6 Add `flows/core_regression.yaml` as the top-level smoke/regression entrypoint that runs all journey flows. + +## 2. Business Logic / Hooks + +- [x] 2.1 Verify no React Native business logic/hook changes are required for this Maestro-only coverage update. + +## 3. Store (Slice + Saga) + +- [x] 3.1 Verify no Redux slice/saga changes are required for this Maestro-only coverage update. +- [x] 3.2 Verify no Redux Persist migration update in `src/store/migrations.ts` is required. + +## 4. Storage + +- [x] 4.1 Verify no Realm schema or MMKV key changes are required for this Maestro-only coverage update. + +## 5. Tests + +- [x] 5.1 Validate new YAML flow files for syntax/style consistency with existing `flows/` conventions. +- [x] 5.2 Run a targeted Maestro flow lint/parse check available in this repository and confirm success. diff --git a/openspec/specs/maestro-core-journey-flows/spec.md b/openspec/specs/maestro-core-journey-flows/spec.md new file mode 100644 index 0000000000..47cc778fd0 --- /dev/null +++ b/openspec/specs/maestro-core-journey-flows/spec.md @@ -0,0 +1,41 @@ +# maestro-core-journey-flows Specification + +## Purpose +Define baseline Maestro regression coverage for Bitcoin Keeper core journeys by specifying composed onboarding/setup, wallet viewing, receive/send, app settings, and key-management flow expectations. +## Requirements +### Requirement: Core journey suite entrypoint +The system SHALL provide a Maestro flow entrypoint that executes core user journeys for onboarding/setup, wallet viewing, receive, send, app settings, and key-management. + +#### Scenario: Full core regression composition +- **GIVEN** Maestro is configured with `${APPID}` and a valid test account context for Wallet and Vault screens +- **WHEN** the tester runs the core regression flow entrypoint +- **THEN** the flow MUST invoke composed subflows for onboarding/setup, wallet viewing, receive/send, app settings, and key-management in a deterministic order + +### Requirement: Journey flows SHALL align with existing selectors and assertions +Each new journey flow MUST reuse established IDs/text assertions from existing Bitcoin Keeper Maestro flows to reduce selector drift and maintenance risk. + +#### Scenario: Selector compatibility with current branch conventions +- **GIVEN** existing Wallet and Signer UI elements expose IDs/text used in current `flows/*.yaml` +- **WHEN** new journey wrapper flows are added +- **THEN** the wrappers MUST reference existing flow files and retain existing assertion behavior instead of introducing unverified selectors + +### Requirement: Receive and send journey coverage +The suite SHALL cover receive and send pathways for a Wallet, including transition into send amount/fee review surfaces that operate on satoshi-backed wallet balances (display format may be BTC). + +#### Scenario: Wallet receive and send composition +- **GIVEN** a Wallet with spendable UTXO state and at least 1100 satoshis available for test sending +- **WHEN** the receive/send journey flow runs +- **THEN** it MUST execute receive and send subflows and reach send confirmation/broadcast UI outcomes without changing Signer protocol behavior + +#### Scenario: Network-dependent send handling +- **GIVEN** Electrum connectivity is offline or unstable during send journey execution +- **WHEN** the receive/send journey flow invokes the send subflow +- **THEN** the flow MUST fail at existing in-app send/network checks rather than bypassing wallet/network validation + +### Requirement: Settings and key-management journey coverage +The suite SHALL include app settings and key-management pathways relevant to Wallet, Vault, and Signer maintenance surfaces. + +#### Scenario: Settings and key surfaces are exercised +- **GIVEN** the test account can access settings and manage keys from current app navigation +- **WHEN** the settings and key-management journey flows run +- **THEN** the composed suite MUST traverse existing settings and key-management subflows and verify expected navigation/assertion checkpoints