Add Playwright test suite (#243)

* Add Playwright for e2e testing
* Add super basic test for the login to ensure auth guard and redirect are working
* Add spec for add-phrase & bulk-add-phrases
* Add stubs for specs for all mutations across the app
* Add proper types to the db-helpers file
* Add working cards spec to test card status dropdown and heart icon
* Document the pattern to check results in both the DB and UI
* Add requests spec
* Always put toasts last so we can use them to await interactions
* Write up some ideas for ideal testing framework
* Add spec for decks
* Add reviews.spec, and both-helpers to compare db to local
* Make everything less flakey

Author: mhsnook

.env.example

@@ -1,6 +1,8 @@
 # cp .env.example .env
 VITE_SUPABASE_URL="http://localhost:54321"
 VITE_SUPABASE_ANON_KEY=""
+# used for playwright e2e tests
+SUPABASE_SERVICE_ROLE_KEY=""
 
 # Build/deploy details
 # TAURI_SIGNING_PRIVATE_KEY=

.gitignore

@@ -30,3 +30,7 @@ tsconfig.tsbuildinfo
 .vercel
 .env*.local
 keystore.properties
+
+# Playwright
+/playwright-report/
+/test-results/

CHANGELOG.md

@@ -5,23 +5,41 @@ _November 2025_
 Since April we have added direct messages, realtime connections for friend requests, alert badges
 to help users discover features and important interactions.
 
-And we have opened up a new feature
-realm with the addition of "Phrase Requests", allowing you to describe a situation you're in and
-what you want to communicate, and ask native speakers to answer with a flash card that will prepare
-you for similar situations in the future. This "requests" concept provides a cross-language meta-
-layer, describing what linguists call "messages" (the actual _thing_ you want to convey), which
-mirrors the way people actually learn languages in the real world: by asking a friend or colleague
-who speaks the language already, "Hey, when I want to hail a cab, what do I say?"
+We have opened up a new feature realm with the addition of "Phrase Requests", allowing users to
+describe a situation and what they want to communicate, and ask native speakers to answer with a
+flash card that will prepare them for similar situations in the future. This "requests" concept
+provides a cross-language meta-layer, describing what linguists call "messages" (the actual _thing_
+you want to convey), which mirrors the way people actually learn languages in the real world: by
+asking a friend or colleague who speaks the language already, "Hey, when I want to hail a cab, what
+do I say?"
 
 In the next phase, this "Requests" concept will become the basis for additional social features,
 and will allow us to identify _across all languages_ which types of cards will be most useful for
 learners of other languages, to help us make the most out of our crowd-sourcing model, so that work
 put into one language can be used to ease the path for others.
 
 To make these more interactive and more social features perform better on device, and require less
-bandwidth and re-fetching from the server, this version also include a major upgrade to the way
+bandwidth and re-fetching from the server, this version include a major upgrade to the way
 data is fetched and stored on device, using Tanstack DB's live queries for all data in the app.
 
+- Preloads almost the entire database in route loaders (we will replace this soon with more precise
+  partial loaders, added in a recent version but not needed yet).
+- Local DB _Collections_ store normalised copies of data, backed by Zod schemas.
+- `useSomeData` style hooks are now based on `useLiveQuery` which allows us to join and filter data,
+  and, importantly, to calculate aggregate data this way so we can replace postgres-view-based
+  aggregation and have our aggregates automatically respond to any inserts into the local database.
+- Collections are initialised, populated, and invalidated/cleared differently to how the query
+  cache worked, so we have to be more careful about race conditions on loading and logout.
+
+To help us manage this new complexity, we have added Playwright for end-to-end testing, which pairs
+well with the Schema-backed runtime validation of our Collections to test all interactions between
+client and server.
+
+- Use Playwright specs to orcestrate browser navigation through all main features of the app,
+  particularly mutations.
+- Use `both-helpers.ts` to query the DB as service role and evaluate the local collection and
+  return both, then compare them in the spec.
+
 ## 0.1 - The MEP
 
 _April 2025_

e2e/example.spec.ts

@@ -0,0 +1,8 @@
+import { test, expect } from '@playwright/test'
+
+test('has title', async ({ page }) => {
+	await page.goto('/')
+
+	// Expect a title "to contain" a substring.
+	await expect(page).toHaveTitle(/Sunlo/)
+})

e2e/global-setup.ts

@@ -0,0 +1,15 @@
+import { execSync } from 'child_process'
+
+async function globalSetup() {
+	console.log('Global Setup: Resetting Supabase Database...')
+	try {
+		// Reset the database to a clean state with seeds
+		execSync('pnpm supabase db reset', { stdio: 'inherit' })
+		console.log('Global Setup: Database reset complete.')
+	} catch (error) {
+		console.error('Global Setup: Failed to reset database.', error)
+		throw error
+	}
+}
+
+export default globalSetup

e2e/helpers/auth-helpers.ts

@@ -0,0 +1,54 @@
+import { expect, Page } from '@playwright/test'
+
+// Test user credentials and IDs from seed data
+export const TEST_USER_UID = 'cf1f69ce-10fa-4059-8fd4-3c6dcef9ba18'
+export const TEST_USER_EMAIL = '[email protected]'
+export const FIRST_USER_UID = 'a2dfa256-ef7b-41b0-b05a-d97afab8dd21'
+export const FIRST_USER_EMAIL = '[email protected]'
+
+/**
+ * Log in with specific credentials
+ */
+export async function login(
+	page: Page,
+	email: string,
+	password: string
+): Promise<void> {
+	await page.goto('/login')
+	await page.fill('input[name="email"]', email)
+	await page.fill('input[name="password"]', password)
+	await page.click('button[type="submit"]')
+	await page.waitForURL(/\/learn/)
+	await expect(
+		page.getByText('Which deck are we studying today?')
+	).toBeVisible()
+}
+
+/**
+ * Log in as the default test user ([email protected])
+ */
+export async function loginAsTestUser(page: Page): Promise<void> {
+	await login(page, TEST_USER_EMAIL, 'password')
+}
+
+export async function loginAsFirstUser(page: Page): Promise<void> {
+	await login(page, '[email protected]', 'password')
+}
+
+export async function loginAsSecondUser(page: Page): Promise<void> {
+	await login(page, '[email protected]', 'password')
+}
+
+export async function loginAsFriendUser(page: Page): Promise<void> {
+	await login(page, '[email protected]', 'password')
+}
+
+/**
+ * Log out the current user
+ */
+export async function logout(page: Page): Promise<void> {
+	// Navigate to profile and click logout
+	await page.goto('/profile')
+	await page.click('button:has-text("Log out")')
+	await page.waitForURL(/\/login/)
+}

e2e/helpers/both-helpers.ts

@@ -0,0 +1,24 @@
+import type { Page } from '@playwright/test'
+import { DailyReviewStateSchema } from '../../src/lib/schemas'
+import { getReviewSessionState } from './db-helpers'
+import { getReviewSessionLocal } from './collection-helpers'
+
+/**
+ * Get review session from both DB and local collection
+ * Returns parsed, type-safe objects for easy comparison
+ */
+export async function getReviewSessionBoth(
+	page: Page,
+	uid: string,
+	lang: string,
+	daySession: string
+) {
+	// Fetch from DB
+	const { data: fromDB } = await getReviewSessionState(uid, lang)
+	const parsedDB = fromDB ? DailyReviewStateSchema.parse(fromDB) : null
+
+	// Fetch from local collection
+	const fromLocal = await getReviewSessionLocal(page, lang, daySession)
+
+	return { fromDB: parsedDB, fromLocal }
+}

e2e/helpers/collection-helpers.ts

@@ -0,0 +1,42 @@
+import type { Page } from '@playwright/test'
+import type { DailyReviewStateType } from '../../src/lib/schemas'
+
+/**
+ * Get review session from local collection
+ */
+export async function getReviewSessionLocal(
+	page: Page,
+	lang: string,
+	daySession: string
+): Promise<DailyReviewStateType | null> {
+	return await page.evaluate(
+		({ lang, daySession }) => {
+			// @ts-expect-error - accessing window global
+			const reviewDaysCollection = window.__reviewDaysCollection
+			if (!reviewDaysCollection) {
+				throw new Error('reviewDaysCollection not attached to window')
+			}
+
+			const key = `${daySession}--${lang}`
+			return reviewDaysCollection.get(key) || null
+		},
+		{ lang, daySession }
+	)
+}
+
+/**
+ * Clear review session from localStorage
+ */
+export async function clearReviewSessionFromLocal(
+	page: Page,
+	lang: string,
+	daySession: string
+) {
+	await page.evaluate(
+		({ lang, daySession }) => {
+			const key = `${daySession}--${lang}`
+			localStorage.removeItem(key)
+		},
+		{ lang, daySession }
+	)
+}