Skip to main content
Synced from the repo — do not edit here

Canonical source: QA_GUIDE.md. This page is generated by docs/scripts/sync-handbook.mjs. Edit the source file in the repo; changes appear here on the next build.

QA Guide — Basis Health Platform

For QA contractors, testers, and reviewers. This guide covers how to review PRs, report bugs, and verify fixes on the Basis Health Platform.

Quick Start​

  1. Get access: Request GitHub repo access and staging environment credentials from the project lead
  2. Read first: Skim CLAUDE.md (project rules) and FEATURES.md (feature status)
  3. Review PRs: Follow the PR Review Checklist below
  4. Report bugs: Use the GitHub Issue templates
  5. Track time: Log hours against issue numbers

Environment Access​

EnvironmentURLPurpose
Productionplatform.basishealth.ioLive — DO NOT test destructive actions here
StagingPreview channel URLs (posted on PRs)Safe to test anything
Emulatorlocalhost:5050 (local only)Full offline testing

Test Accounts​

Use the Admin role for testing (not System Admin — it bypasses permission checks).

Ask the project lead for:

  • Staging clinic ID
  • Test user credentials
  • Stripe test mode keys (if testing payments)

PR Review Checklist​

Every PR review should cover these areas:

1. Functional Verification​

  • Changes match the PR description
  • New features work as described
  • Edge cases handled (empty states, long text, missing data)
  • Error states show user-friendly messages (toasts, not browser alerts)

2. HIPAA Compliance (Critical)​

  • No patient health information (PHI) in console logs
  • No PHI in error messages shown to users
  • Permission checks present before accessing patient data
  • Audit trail created for significant operations

3. Platform Rules​

  • Uses clinicsv2 collection (never legacy clinics)
  • Uses safeOnSnapshot (never raw onSnapshot)
  • Uses useToast() for user feedback (never alert())
  • Uses camelCase for all Firestore field names
  • Firestore data access has fallbacks (field || '', field ?? 0)

4. Security​

  • No hardcoded secrets, API keys, or credentials
  • No SQL/command injection vectors
  • Auth checks present on Cloud Functions
  • CORS origins include localhost:3000 for local dev

5. UI/UX​

  • Responsive on desktop (1024px+) and tablet (768px+)
  • Loading states shown during async operations
  • Empty states are informative (not blank screens)
  • Toast shown on success AND error for every async action

Bug Report Process​

Step 1: Reproduce​

Before reporting, confirm the bug is reproducible:

  • Try in an incognito/private window
  • Try with a different test account
  • Check if it's browser-specific

Step 2: File Issue​

Use the Bug Report template on GitHub Issues. Include:

  • Steps to reproduce (numbered, specific)
  • Expected behavior
  • Actual behavior
  • Screenshot or screen recording (required for UI bugs)
  • Browser, OS, and role used during testing

Step 3: Severity​

Label your bug with the correct severity:

LabelMeaningExamples
P0Production down, data loss, security breachAuth bypass, data corruption, site unreachable
P1Major feature broken, no workaroundCan't book appointments, payments fail
P2Feature broken but workaround existsFilter doesn't work but search does
P3Cosmetic, minor enhancementTypo, alignment off, color inconsistency

QA Report Template​

After completing a full QA pass on a PR, post a review comment using this format:

## QA Report

**Tested by:** [Your name]
**Date:** [Date]
**Environment:** [Staging URL or local]
**Role:** [Admin / Manager / Medical / etc.]
**Browser:** [Chrome 120 / Safari 17 / etc.]

### Test Results

| Test Case | Status | Notes |
|-----------|--------|-------|
| [Feature/scenario 1] | PASS/FAIL | [Details] |
| [Feature/scenario 2] | PASS/FAIL | [Details] |

### HIPAA Checklist
- [ ] No PHI in console (DevTools → Console)
- [ ] No PHI in network responses (DevTools → Network)
- [ ] Permission errors show generic message

### Issues Found
1. [Issue description + screenshot]
2. [Issue description + screenshot]

### Verdict
- [ ] **APPROVED** — Ready to merge
- [ ] **CHANGES REQUESTED** — Issues must be fixed first
- [ ] **BLOCKED** — Cannot test (missing data/access/etc.)

Testing Specific Areas​

Scheduling & Booking​

  • Create, edit, cancel appointments
  • Test recurring appointments
  • Test availability conflicts
  • Test with different service types and durations

Payments & Billing​

  • Use Stripe test cards (4242 4242 4242 4242)
  • Test membership subscription creation/cancellation
  • Verify invoice generation
  • Test failed payment scenarios (4000 0000 0000 0002)

AI / Copilot​

  • Test Copilot responses for accuracy
  • Verify knowledge base search returns relevant results
  • Test with different clinic configurations
  • Check that AI responses don't contain PHI

Client Portal (basisweb)​

  • Test patient-facing flows (booking, viewing protocols)
  • Verify document upload/download
  • Test on mobile viewport (375px width)

Merge Process​

  1. QA reviewer posts QA Report on PR
  2. If APPROVED: Add qa:pass label
  3. Project lead reviews and merges
  4. Staging deploy auto-triggers on merge
  5. Production deploy requires manual approval

Never merge without: QA report + qa:pass label + at least 1 human approval

Common Pitfalls​

PitfallHow to Catch
Testing as System AdminSystem Admin bypasses all permission checks — always test as Admin role
Missing toast on errorTrigger an error (disconnect WiFi, use invalid data) — should see a toast, not silence
Raw onSnapshot listenerSearch PR diff for onSnapshot( — should always be safeOnSnapshot(
Stale Firestore permissionsAfter rule changes, hard-refresh (Cmd+Shift+R) — cached listeners cache denials
Date timezone issuesTest with users in different timezones — dates should not shift by 1 day

Contact​

  • GitHub Issues: Primary communication channel
  • Slack: #basis-dev for real-time questions
  • Escalation: Tag project lead on critical/blocking issues