Skip to content

docs(testing): document the Tier 0–4 BitBox test strategy#347

Merged
TaprootFreak merged 1 commit into
developfrom
docs/testing-tiers
May 15, 2026
Merged

docs(testing): document the Tier 0–4 BitBox test strategy#347
TaprootFreak merged 1 commit into
developfrom
docs/testing-tiers

Conversation

@TaprootFreak
Copy link
Copy Markdown
Contributor

Closes Acceptance Criterion #6 of #314"Documentation: `docs/testing.md` explains when to use which tier, with examples."

Summary

A single page that captures everything we've learned across Phase 0 (#319) and Phase 1 Foundation (#320 / #321) about how to test BitBox-touching code without re-deriving the rules every PR:

  • Tier matrix (0–4) with hardware / CI status for each, so reviewers can tell at a glance what a test does and doesn't prove
  • Decision tree for picking a tier — "if a Tier 0 test would have to mock the very thing under test, drop down a tier"
  • Tier 0 patterns with concrete excerpts from real test files:
    • Cubit / Bloc tests (`bloc_test` + `mocktail.Mock`) pointing at `test/screens/kyc/cubits/kyc/kyc_cubit_test.dart`
    • Widget tests (`pumpApp` + `MockCubit`) pointing at `test/screens/kyc/steps/kyc_email_page_test.dart`
    • Service + HTTP tests (`http/testing` `MockClient` + `_MockAppStore`) pointing at `test/packages/service/dfx/dfx_bank_account_service_test.dart`, including the `setAuthToken('test-jwt')` pre-seed trick for DFXAuthService-derived services (the gotcha that broke CI on fix: keep dashboard buy actions visible #321)
  • Tier 1 patterns for `FakeBitboxCredentials` with the `FakeBitboxBehavior` matrix and the disconnect-flip-to-success reconnect pattern, pointing at `test/integration/kyc_sign_flow_test.dart`
  • Tiers 2–4 marked deferred with status pointers back to the corresponding phase of Comprehensive BitBox testing infrastructure (Tier 0–4) #314
  • Mocktail gotchas (`Future` + `thenAnswer`, `registerFallbackValue`, private mocks)
  • Add-tests checklist for PRs touching `KycCubit` / `Eip712Signer` / `DFXAuthService` / `BitboxCredentials` / `bitbox_flutter`

CONTRIBUTING.md's Testing section gets a one-line cross-link.

Test plan

  • Doc compiles / renders (no broken intra-repo links in the markdown)
  • Every code example matches a real file already on `develop`
  • `flutter analyze` — no new issues (4 pre-existing errors in `test/screens/home/home_bloc_test.dart` are unrelated to this PR; verified they exist on `develop` too)

Closes Acceptance Criterion #6 of #314: `docs/testing.md` explains when
to use which tier with concrete examples from the repo, plus the cubit /
widget / service+HTTP patterns and the `FakeBitboxCredentials` modes
that Tier 1 already ships.

- Decision tree for picking a tier based on what behaviour you need to
  prove
- Tier 0 patterns pointing at `kyc_cubit_test.dart`,
  `kyc_email_page_test.dart`, `dfx_bank_account_service_test.dart`
  (including the `setAuthToken` pre-seed for DFXAuthService-derived
  services)
- Tier 1 patterns pointing at `fake_bitbox_credentials.dart` and
  `kyc_sign_flow_test.dart`, with the FakeBitboxBehavior matrix
- Tier 2 / 3 / 4 marked deferred with status pointers back to #314's
  phases
- Mocktail gotchas (Future + thenAnswer, registerFallbackValue)
- Adding-tests checklist for PRs touching KycCubit, Eip712Signer,
  DFXAuthService, BitboxCredentials, or bitbox_flutter

Cross-links from CONTRIBUTING.md's Testing section.
@TaprootFreak TaprootFreak marked this pull request as ready for review May 15, 2026 12:14
@TaprootFreak TaprootFreak merged commit 64eac27 into develop May 15, 2026
1 check failed
@TaprootFreak TaprootFreak deleted the docs/testing-tiers branch May 15, 2026 12:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant