Onboarding QA Guide

Scope: End-to-end test plan for every onboarding path on Kulcare — practitioner (virtual + clinic), wellness vendor, sales-led, existing-tenant facility add, and the cross-cutting role gates.

Prerequisites: Backend + frontend dev servers running, fresh kulcare_development DB, at least one Razorpay test merchant available for vendor-side tests (Phase 4 only).

Related: Onboarding feature doc · Vendor self-serve V1 plan · Polymorphic professional pattern · CMS referrals feature doc · Referrals: CMS create flow + recipient picker

1. Test environment setupCopy Anchor Link

1.1 DatabaseCopy Anchor Link

cd backend
RAILS_ENV=test bundle exec rails db:drop db:create db:migrate
psql -d kulcare_test -c "CREATE EXTENSION IF NOT EXISTS pgcrypto"   # required for User PK gen_random_bytes

For dev (where you'll click through the flows in a browser):

bundle exec rails db:migrate
bundle exec rake dev_seed:generate_accounts   # creates the seeded test users

1.2 Test users (seeded)Copy Anchor Link

The seed creates accounts representing each signed_up_as value. Phone numbers double as login IDs (OTP flow):

To reset a State A user back to State A after they've onboarded (for re-running the wizard):

# bundle exec rails runner
ActiveRecord::Base.transaction do
  user = Identity::User.find_by(phone_country_code: '91', phone_number: '5555556000')
  Identity::UserMembership.where(user_id: user.id).destroy_all
  Identity::PractitionerRole.where(practitioner_id: user.practitioner&.id).destroy_all if user.practitioner
  Identity::Tenant.where(name: 'Acme').destroy_all
end

For the vendor user, also Identity::Vendor.where(user_id: user.id).destroy_all (cascades the Connect profile).

1.3 AuthCopy Anchor Link

Sign in via /signin using the phone number. OTP is logged to log/development.log in dev; grep for the user's phone number to find the verification code.

1.4 What "State A" meansCopy Anchor Link

A user is in State A when they have no tenant memberships AND no vendor record. The State A surface (path-selector cards) renders only when both conditions hold. After the wizard completes (either path), the user is in State B and the cards disappear.

2. Role × surface matrixCopy Anchor Link

What each role should see, per surface, on a clean cache after sign-in.

2.1 Path-selector cards on /connect/dashboardCopy Anchor Link

The cards show only while Connect onboarding is not complete. After onboarding, they do not show.

A practitioner who completed onboarding and has no tenant sees one line: "Where do you see patients? Ask the facility admin for an invite, or set up your own." Each part is a link (/connect/invites, /connect/facility/new).

2.1a The dashboard after onboardingCopy Anchor Link

2.2 Connect sidebarCopy Anchor Link

Inbox has an inbox icon. Notifications has the bell. A practitioner who ticked "teaches" gets no "Classes" entry: /connect/packages is for vendor accounts.

"My profile" opens /connect/profile for every role. The page it shows depends on the role. A vendor sees the vendor profile. A practitioner, a facility owner and a staff member see the practitioner profile.

2.3 Talk-to-Sales FAB (bottom-right)Copy Anchor Link

2.4 Add Clinic CTAsCopy Anchor Link

3. Practitioner self-serve flowsCopy Anchor Link

3.1 Solo virtual practice (State A)Copy Anchor Link

3.2 Multi-doctor clinic (State A)Copy Anchor Link

3.3 Multi-stakeholder (any practitioner sub-flow)Copy Anchor Link

3.4 Add a facility under existing tenantCopy Anchor Link

3.5 Owner/admin gate on /connect/facility/newCopy Anchor Link

4. Vendor self-serve flow (wellness)Copy Anchor Link

4.1 Vendor wizard (State A)Copy Anchor Link

4.2 Vendor profile pageCopy Anchor Link

4.3 Vendor stub pages (Phases 2 + 4)Copy Anchor Link

4.4 Vendor sees the global FABCopy Anchor Link

4.5 Backend vendor stateCopy Anchor Link

After V8, verify:

vendor = Identity::Vendor.last
vendor.user_id == user.id
vendor.tenant_id.nil?
vendor.connect_can_receive_referrals? == false  # accepting_referrals: false initially
profile = vendor.professional_profile
profile.visibility == 'unlisted'
profile.slug.present?  # auto-generated, format /\A[a-z0-9\-]+\z/

4.6 Vendor packages (V1 Phase 2)Copy Anchor Link

4.6a Vendor practice: clients, payments, bookings (plan 2026-10-08)Copy Anchor Link

4.7 Polymorphic ServicePackage cross-tenant invariantsCopy Anchor Link

5. Sales-led flow (any role)Copy Anchor Link

5.1 Path-selector "Talk to sales" cardCopy Anchor Link

5.2 Global FAB (cross-surface)Copy Anchor Link

5.3 Backend ProductLead behaviorCopy Anchor Link

6. Virtual-to-physical graduationCopy Anchor Link

6.1 The "Add a physical location" cardCopy Anchor Link

7. Polymorphic referral receiver (vendor as referee)Copy Anchor Link

This is the only "after onboarding" flow worth re-testing here — it's the surface where vendor identity meets the existing clinical referral flow.

The CMS-side create flow (/cms/referrals + /cms/referrals/new) is exercised in §7A below. This section (R1–R7) covers the underlying validation + notification invariants regardless of UI entry point.

7A. CMS referral creation flow (sender side)Copy Anchor Link

/cms/referrals (list) + /cms/referrals/new (create with the unified picker). Backed by GET /clinical/referrals/recipients + POST /clinical/referrals. Shipped in PR #1314. Feature doc: cms-referrals.md. Developer reference: Referrals: CMS create flow.

7A.1 List pageCopy Anchor Link

7A.2 Recipient pickerCopy Anchor Link

7A.3 Submit + resultCopy Anchor Link

7A.4 AuthorizationCopy Anchor Link

7A.5 Polymorphic invariants in the pickerCopy Anchor Link

8. Auth state self-healCopy Anchor Link

Critical for users who hit /cms/* after creating a tenant in another tab, or after a wizard race.

9. Cross-cutting role gatesCopy Anchor Link

Things to visually confirm in Chrome DevTools React tab if a flow misbehaves.

10. Known limitations / out of scopeCopy Anchor Link

• Razorpay merchant linking for vendors lands in V1 Phase 4. Today the Payments page is a stub.
• Vendor scheduling lands in V1.5. Today vendors coordinate first sessions manually post-purchase.
• Vendor packages land in V1 Phase 2. Today the Packages page is a stub.
• Patient-facing vendor browse (patient app) lands in V1 Phase 3.
• Cross-vendor referrals (vendor → vendor) are V2. Vendors can only RECEIVE referrals from clinic doctors today.
• Practitioner who is also a vendor: Connect::BasePolicy#user_profile resolves practitioner first. A practitioner who later signs up as a vendor will silently lose vendor profile access. Tracked for vendor V1 with an ?as=vendor toggle.
• Subscription gating for unpaid tenants: not enforced. New tenants land in trial state without payment. Phase 2.
• Refund initiation: V1 default is "vendors handle refunds via Razorpay merchant dashboard". Kulcare does not initiate refunds.

11. Common gotchasCopy Anchor Link

• Stale availableProfiles after creating a tenant in another tab → self-heal effect fixes on next mount; if it's still broken, sign out + back in.
• signed_up_as: 'patient' users land in the patient app, not Connect. The Connect path-selector won't render for them.
• Test DB lacks pgcrypto after db:drop db:create db:migrate (structure.sql doesn't capture the extension). Re-run psql -d kulcare_test -c "CREATE EXTENSION IF NOT EXISTS pgcrypto" whenever you reset.
• Modal swallows thrown errors: TalkToSalesModal keeps itself open with selections intact when onSubmit throws. Caller is responsible for the toast — the modal won't surface the error inline.
• Vendor profile starts unlisted, not public. Payment account activation makes it public (Connect::PublishVendorListing), unless the vendor turned "Show in search" off or staff delisted them. For vendors that were active before this change, run rake connect:publish_active_vendors (a dry run unless CONFIRM=1).
• ServicePackage default scope does NOT include unscoped_by_tenant calls — the custom default scope on the model already passes through vendor-owned rows (rows with tenant_id IS NULL). Use Identity::ServicePackage.for_vendor(vendor) for vendor reads; Identity::ServicePackage.for_tenant(tenant) for tenant reads. See polymorphic ServicePackage owner guide.
• vendor.service_packages is NOT defined. The polymorphic side names the association owner. Use Identity::ServicePackage.for_vendor(vendor) instead.

12. Spec coverage mapCopy Anchor Link

Where automated coverage lives today (and what it does NOT cover).

No automated coverage for: the frontend wizard / vendor packages pages (manual only), the path-selector role filtering, the global FAB visibility logic, the auth-state self-heal, or the virtual-to-physical graduation card. The polymorphic ServicePackage model + policy + controller specs are also pending (the existing model spec has pre-existing factory failures unrelated to the polymorphic refactor; needs a fresh-rewrite pass). All worth adding as Vitest + Playwright tests in a follow-up.

Status: living document; update when a new flow ships Last Updated: 2026-05-05