test: Guided Tours & Onboarding UX — Driver.js tours for all roles

[guillermoscript]

Scope

Interactive onboarding tours built with Driver.js. Five tours cover admin, teacher, student dashboards plus course and lesson editors. Tours auto-start on first visit and can be replayed via the HelpCircle trigger button.

Personas

Persona	Email	Role
Admin/Owner	owner@e2etest.com	admin (Default School)
Teacher	owner@e2etest.com	admin/teacher (Default School)
Student	student@e2etest.com	student

Tours Under Test

Tour ID	Route	Auto-start trigger
admin-dashboard	/dashboard/admin	First visit
teacher-dashboard	/dashboard/teacher	First visit
student-dashboard	/dashboard/student	First visit
course-editor	/dashboard/teacher/courses/[id]	First visit
lesson-editor	/dashboard/teacher/courses/[id]/lessons/[id]	First visit

Test Cases

Auto-Start Behavior

• Admin logs in fresh (clear localStorage) → admin-dashboard tour starts after 800ms on /dashboard/admin
• Teacher logs in fresh → teacher-dashboard tour starts on /dashboard/teacher
• Student logs in fresh → student-dashboard tour starts on /dashboard/student
• Tour has already run (localStorage key tour-completed:{tourId}:{userId} set) → no auto-start

Tour Steps

• Each tour step highlights the correct data-tour element
• Step popover shows title + description text (translated in both en and es)
• "Next" button advances to next step
• "Back" button returns to previous step
• "Skip" / "X" button dismisses tour entirely
• Final step "Done" button completes tour

Replay (TourTrigger button)

• HelpCircle icon visible in dashboard header/sidebar
• Clicking it clears localStorage key and restarts tour immediately
• Works for all 5 tour types

Reduced Motion

• With prefers-reduced-motion: reduce in OS settings → tour animations disabled, steps still functional

Course Editor Tour

• Tour highlights: course settings, lessons panel, exams panel, preview button
• Runs on first visit to /dashboard/teacher/courses/[id]

Lesson Editor Tour

• Tour highlights: content editor, lesson settings, save button
• Runs on first visit to lesson editor

i18n

• All tour step titles and descriptions in en locale render correctly
• Switch locale to es → tour texts in Spanish

Definition of Done

• All 5 tours start on first visit and complete without error
• Replay works via trigger button
• LocalStorage key correctly prevents re-auto-start
• No JS errors during tour execution
• Tour steps point to existing DOM elements (no "element not found" errors)

[guillermoscript]

QA — found & fixed: Replay tour was dead (PR #309, merged)

Tested student-dashboard tour as alice@student.com.

🐛 Bug — "Replay tour" silently did nothing

With the global tours-disabled kill-switch in localStorage (left over from E2E runs), clicking the HelpCircle replay did nothing — no tour, no feedback. Root cause: isTourCompleted() lumps the kill-switch + per-tour flag together, and the replay path re-runs the same autoStart && !isTourCompleted(...) gate. Fixed with a forceStart prop that makes an explicit replay bypass both gates (kill-switch only gates auto-start now). All 6 tour wrappers updated.

✅ Verified

Check	Result
Replay starts tour (even with tours-disabled set)	✅ after fix
Step popover title + description (translated)	✅ "Welcome to Your Dashboard" → "Your Progress at a Glance"
"Next" advances steps	✅ 1/6 → 2/6
Each step highlights correct data-tour element	✅ student-welcome → student-stats
"X" dismisses tour	✅
Step counter	✅ "N of 6"
data-tour targets present	✅ student-welcome, student-stats, student-checklist, student-courses, student-sidebar, sidebar-browse, sidebar-progress
Tour i18n parity (en/es)	✅ all 6 tour namespaces match key-for-key (12/22/12/10/11/12)

Not exercised

Fresh-localStorage auto-start timing (800ms), reduced-motion path (code: prefers-reduced-motion disables animate), and the course/lesson-editor tours (same GuidedTour mechanism — fix applies to all 6 wrappers).