QA contractor onboarding

This doc is what a new QA contractor (Fiverr / Upwork / internal) reads to come up to speed on FitKit. Read it end to end before opening the app.

What FitKit is (one paragraph)

FitKit is a web platform for fitness studios, online coaches, and personal trainers — primarily in Israel. Studio owners use it to run their business (memberships, billing, class scheduling, coaching, member management); members use it to book classes, follow programs, log results, and communicate with their coach.

Read docs/overview/product-vision.md for the longer version. Read docs/overview/personas.md next — you’ll need it to understand which user type you’re acting as in each test.

Personas you’ll test as

In small operators these overlap — a personal trainer is owner + coach simultaneously. You’ll switch contexts often.

Environments

No long-lived staging today. You’ll mostly test PR previews. When a PR is opened, GitHub posts a Vercel preview URL — that’s where you go.

Test accounts

The product team will share credentials per environment. Typical set:

• qa-owner@fitkit-test.dev — Studio Owner of a dummy org. Use this to exercise dashboard surfaces.
• qa-coach@fitkit-test.dev — Coach in the same org. Use this to verify coach-only flows.
• qa-member@fitkit-test.dev — Member of the same org. Use this for booking, logging, etc.
• Optional second org accounts if cross-org isolation is being tested.

If you don’t have credentials, ask the engineer who assigned the test. Don’t reuse accounts across non-isolated tests — schedule conflicts and stale state will bite you.

Languages and direction

What RTL means (if you haven’t seen it before)

In Hebrew, the entire interface mirrors:

• Text flows right-to-left.
• Page layout flows right-to-left — sidebars on the right, content on the left, navigation chevrons pointing leftward to mean “forward”.
• Forms have labels on the right, error icons on the left.
• Lists, tables, modals, drawers — everything mirrors.

Common RTL bugs to watch for:

• An icon that points the wrong way (“next” arrow pointing into the page rather than away from it).
• A drawer that slides in from the wrong edge.
• Text overflow that gets clipped on the wrong side.
• Mixed Hebrew + English content where the English fragment breaks the flow.
• Numbers that look right but are reversed (e.g. dates rendered MM/DD when they should be DD/MM).

When you find a layout issue, always note which locale. The same screen may be perfect in English and broken in Hebrew.

Devices

Use real devices when possible; Chrome DevTools mobile emulation catches layout but not OS-specific quirks (iOS keyboard interactions, Android share intents).

What you’re testing per feature

Per-feature QA plans live at docs/features/<feature>/qa-plan.md. When you pick up a feature, read that file first. A typical QA plan covers:

• The user-visible scope of the feature.
• Each user journey to walk through (Happy Path + edge cases).
• Locales to verify.
• Devices to verify.
• Known limitations (so you don’t report them as bugs).

If a qa-plan.md doesn’t exist for a feature you’ve been asked to test, ask the engineer to write one — don’t guess.

Bug report template

Use this format. Engineers will reject reports that miss the basics.

**Title:** [Feature] Concise summary of the problem
 
**Environment:**
- URL: https://...
- Persona / account: qa-coach@...
- Browser + version: Chrome 135.0
- Device: iPhone 15 Pro, iOS 18.2 / Desktop / etc.
- Locale: he | en | ru
- Date/time observed (TZ): 2026-05-28 14:30 Asia/Jerusalem
 
**Steps to reproduce:**
1. ...
2. ...
3. ...
 
**Expected:**
What should have happened, per the qa-plan or product behaviour.
 
**Actual:**
What did happen.
 
**Evidence:**
- Screenshot / video (attached)
- Console errors (paste the text or attach the screenshot of DevTools console)
- Network errors (if a failed API call — include the X-Request-Id response header value if available)
 
**Notes:**
Anything else: was it reproducible on a second run? Did it happen in other locales?

The X-Request-Id trick

Every API response includes an X-Request-Id header. When you find a bug that triggers a server error, open DevTools → Network → the failed request → Response Headers, copy that id, and put it in the bug report. Engineers can pivot from that id directly into Sentry and Pino logs.

What you’re not testing (current limitations)

These exist today and are not bugs unless the qa-plan says otherwise:

• Spotter (AI assistant) is coach-only. Members don’t see it. If a member-side AI surface is missing, that’s expected.
• WhatsApp notifications. Not shipped yet. Email + web push are the only channels.
• Multi-location. Schema supports it; UX is single-location for now.
• Audit log in the UI. Schema exists; the admin browser is on the roadmap (FIT-20). No audit-trail screen.
• Analytics dashboard v1. Insights widgets exist; full reporting (cohorts, churn forecast) is not shipped.
• Native mobile apps. PWA only.
• Locale switching mid-session. Switching from he → en requires a full reload or fresh navigation.

If you’re not sure whether something is a bug or a known limitation, ask before filing.

Cadence

Default cadence (varies per engagement):

• Daily: Smoke-test the PR previews you’ve been assigned. Report blockers same-day.
• Per feature: Walk the qa-plan in full. Locale matrix + device matrix.
• Weekly: Send a short summary of bugs filed, bugs verified-fixed, and pending items.

Talk to your engineering contact early if the cadence isn’t workable — better to renegotiate than miss.

Where to find what

Reaching the team

For every bug filed, include the engineer or PM contact in the channel agreed at engagement start. Use Linear (preferred) or whatever the engineer specifies. Don’t DM — bugs in shared channels stay findable.

Quick checklist before submitting a bug

• Title is specific (no “doesn’t work” titles)
• Reproducible — you saw it twice, or you have a video
• Environment + persona + locale + device captured
• Screenshot or video attached
• Console + network errors checked
• X-Request-Id captured if a server error
• Confirmed it’s not a known limitation
• Posted in the agreed channel