e2e tests playwright & chromatic

.github/workflows/playwright.yml

@@ -0,0 +1,80 @@
+name: E2E tests
+on:
+  push:
+    branches: [master, staging, e2e-tests] # TODO: remove e2e-tests branch after testing
+  pull_request:
+    branches: [master, staging, e2e-tests] # TODO: remove e2e-tests branch after testing
+jobs:
+  playwright:
+    runs-on: ubuntu-latest
+    env:
+      CI: true
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Wait for Netlify Deploy
+        id: netlify_deploy
+        uses: pettinarip/[email protected]
+        with:
+          site_id: "e8f2e766-888b-4954-8500-1b647d84db99"
+          max_timeout: 3600
+        env:
+          NETLIFY_TOKEN: ${{ secrets.NETLIFY_TOKEN }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v2
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Install Playwright with all browsers
+        run: npx playwright install --with-deps
+
+      - name: Run E2E Tests on Netlify URL
+        run: pnpm test:e2e
+        env:
+          PLAYWRIGHT_TEST_BASE_URL: ${{ steps.netlify_deploy.outputs.url }}
+
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: playwright-report
+          path: ./tests/e2e/__results__
+          retention-days: 7
+
+  chromatic:
+    name: chromatic
+    needs: playwright
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22.12.0
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v2
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Download Playwright test results
+        uses: actions/download-artifact@v4
+        with:
+          name: playwright-report
+          path: ./tests/e2e/__results__
+
+      - name: Run Chromatic
+        uses: chromaui/action@latest
+        with:
+          projectToken: ${{ secrets.CHROMATIC_E2E_TOKEN }}
+          playwright: true
+          exitZeroOnChanges: true
+          storybookBaseDir: .
+        env:
+          CHROMATIC_ARCHIVE_LOCATION: ./tests/e2e/__results__

.gitignore

@@ -63,4 +63,5 @@ src/data/crowdin/bucketsAwaitingReviewReport.csv
 
 # Storybook
 build-storybook.log
+build-archive.log
 storybook-static

docs/e2e-testing.md

@@ -0,0 +1,152 @@
+# E2E Testing with Playwright
+
+## Overview
+
+This project uses [Playwright](https://playwright.dev/) for end-to-end testing with [Chromatic](https://www.chromatic.com/) integration for visual regression testing.
+
+## Quick Start
+
+### Running Tests Locally
+
+```bash
+# Install dependencies (if not already done)
+pnpm install
+
+# Install Playwright browsers
+npx playwright install
+
+# Start development server (in a separate terminal)
+pnpm dev
+
+# Run all e2e tests
+pnpm test:e2e
+
+# Run tests with UI (interactive mode)
+pnpm test:e2e:ui
+
+# Run tests in debug mode
+pnpm test:e2e:debug
+
+# View test report
+pnpm test:e2e:report
+```
+
+### Development Server: Choosing the Best Mode for E2E Testing
+
+By default, Playwright tests run against `http://localhost:3000`. Before running tests, ensure your development server is up and running. You can start it in development mode with:
+
+```bash
+pnpm dev
+```
+
+**Note:** Running in dev mode (`pnpm dev`) is convenient for rapid iteration, but it can be significantly slower than production builds. As a result, you may encounter Playwright timeout errors if pages take too long to load or build on demand.
+
+#### Tips to Avoid Timeout Issues
+
+- **Preload pages:** Manually visit the routes you plan to test in your browser before running the tests. This triggers Next.js to build those pages ahead of time, reducing load times during testing.
+- **Increase Playwright timeouts:** If you must use dev mode, consider increasing Playwright's default timeouts to accommodate slower builds (see Playwright config docs).
+- **Use a production build for reliability:** For the fastest and most stable E2E test runs, use a production build. This ensures all pages are prebuilt and served at optimal speed:
+
+```bash
+pnpm build
+pnpm start
+```
+
+This will serve your app at `http://localhost:3000` in production mode, minimizing the risk of timeouts and making your tests more reliable.
+
+> **Summary:**
+>
+> - Use `pnpm dev` for quick local development and debugging, but expect slower performance and possible timeouts.
+> - For CI or full test runs, prefer `pnpm build && pnpm start` for best results.
+
+## Directory Layout
+
+```
+tests/e2e/
+├── __results__/          # Test results (gitignored)
+├── __report__/           # HTML reports (gitignored)
+├── fixtures/             # Test data and fixtures
+├── pages/                # Page Object Model classes
+├── utils/                # Test utilities and helpers
+├── *.spec.ts             # Test files
+└── .gitignore
+```
+
+## Writing Tests
+
+### Best Practices
+
+#### 1. Use Page Object Model
+
+Create reusable page objects for common interactions. For more details, see the [Playwright Page Object Model documentation](https://playwright.dev/docs/pom):
+
+```typescript
+// pages/HomePage.ts
+export class HomePage {
+  constructor(private page: Page) {}
+
+  async goto() {
+    await this.page.goto("/")
+  }
+
+  async searchFor(query: string) {
+    const isMobile = await this.isMobileViewport()
+    if (isMobile) {
+      await this.page.getByTestId("search-button").first().click()
+    } else {
+      await this.page.getByTestId("search-input-button").first().click()
+    }
+    await this.page.getByPlaceholder("Search").fill(query)
+  }
+
+  private async isMobileViewport() {
+    const viewport = this.page.viewportSize()
+    return viewport && viewport.width <= 768
+  }
+}
+```
+
+#### 2. Robust Selectors
+
+Prefer `data-testid` attributes over CSS selectors:
+
+```typescript
+// Good
+await page.getByTestId("search-button")
+
+// Better for accessibility
+await page.getByRole("button", { name: "Search" })
+
+// Avoid fragile selectors
+await page.locator(".search-btn-class") // Fragile
+```
+
+#### 3. Responsive Testing
+
+Handle different viewport sizes appropriately:
+
+```typescript
+test("search functionality", async ({ page }) => {
+  const viewport = page.viewportSize()
+  const isMobile = viewport && viewport.width <= breakpointAsNumber.md
+
+  if (isMobile) {
+    // Mobile-specific logic
+  } else {
+    // Desktop-specific logic
+  }
+})
+```
+
+#### 4. Visual Testing
+
+Use Chromatic snapshots for visual regression testing:
+
+```typescript
+import { takeSnapshot } from "@chromatic-com/playwright"
+
+test("visual regression", async ({ page }, testInfo) => {
+  await page.goto("/")
+  await takeSnapshot(page, "homepage-initial", testInfo)
+})
+```

package.json

@@ -23,7 +23,11 @@
     "events-import": "ts-node -O '{ \"module\": \"commonjs\" }' src/scripts/events-import.ts",
     "crowdin-needs-review": "ts-node -O '{ \"module\": \"commonjs\" }' src/scripts/crowdin/reports/generateReviewReport.ts",
     "update-tutorials": "ts-node -O '{ \"module\": \"commonjs\" }' src/scripts/update-tutorials-list.ts",
-    "prepare": "husky"
+    "prepare": "husky",
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
+    "test:e2e:debug": "playwright test --debug",
+    "test:e2e:report": "playwright show-report tests/e2e/__report__"
   },
   "dependencies": {
     "@crowdin/crowdin-api-client": "^1.25.0",
@@ -97,8 +101,10 @@
     "yaml-loader": "^0.8.0"
   },
   "devDependencies": {
+    "@chromatic-com/playwright": "^0.12.4",
     "@chromatic-com/storybook": "1.5.0",
     "@netlify/plugin-nextjs": "^5.10.0",
+    "@playwright/test": "^1.52.0",
     "@storybook/addon-essentials": "8.6.14",
     "@storybook/addon-interactions": "8.6.14",
     "@storybook/addon-links": "8.6.14",
@@ -120,7 +126,7 @@
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "autoprefixer": "^10.4.19",
-    "chromatic": "10.9.6",
+    "chromatic": "12.0.0",
     "decompress": "^4.2.1",
     "dotenv": "^16.5.0",
     "eslint": "^8.57.1",
@@ -152,5 +158,5 @@
     "unist-util-visit": "^5.0.0",
     "xml2js": "^0.6.2"
   },
-  "packageManager": "[email protected].3+sha512.467df2c586056165580ad6dfb54ceaad94c5a30f80893ebdec5a44c5aa73c205ae4a5bb9d5ed6bb84ea7c249ece786642bbb49d06a307df218d03da41c317417"
+  "packageManager": "[email protected].4"
 }

playwright.config.ts

@@ -0,0 +1,61 @@
+import path from "path"
+
+import dotenv from "dotenv"
+import type { ChromaticConfig } from "@chromatic-com/playwright"
+import { defineConfig, devices } from "@playwright/test"
+
+dotenv.config({ path: path.resolve(__dirname, ".env.local") })
+
+export default defineConfig<ChromaticConfig>({
+  testDir: "./tests/e2e",
+  outputDir: "./tests/e2e/__results__",
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : 3,
+  reporter: [
+    ["html", { outputFolder: "./tests/e2e/__report__" }],
+    ["line"],
+    process.env.CI ? ["github"] : ["list"],
+  ],
+  use: {
+    baseURL: process.env.PLAYWRIGHT_TEST_BASE_URL || "http://localhost:3000",
+    trace: "on-first-retry",
+    screenshot: "only-on-failure",
+
+    // Global test timeout
+    actionTimeout: 10000,
+    navigationTimeout: 30000,
+
+    // Chromatic settings
+    disableAutoSnapshot: true,
+  },
+
+  // Global test timeout
+  timeout: 30000,
+
+  // Expect timeout
+  expect: {
+    timeout: 10000,
+  },
+  projects: [
+    /* Test against desktop browsers */
+    {
+      name: "chromium",
+      use: { ...devices["Desktop Chrome"] },
+    },
+    {
+      name: "webkit",
+      use: { ...devices["Desktop Safari"] },
+    },
+    /* Test against mobile viewports. */
+    {
+      name: "Mobile Chrome",
+      use: { ...devices["Pixel 5"] },
+    },
+    {
+      name: "Mobile Safari",
+      use: { ...devices["iPhone 12"] },
+    },
+  ],
+})