@alliance-droid/svelte-docs-system 0.0.1

package/docs/E2E_TESTS.md

@@ -0,0 +1,354 @@
+# End-to-End Tests (E2E) Specification
+
+This document specifies the E2E tests for the Svelte Documentation System using Playwright.
+
+## Test Environment Setup
+
+These tests require Playwright to be installed:
+
+```bash
+npm install --save-dev @playwright/test
+npx playwright install
+```
+
+## Running E2E Tests
+
+```bash
+npm run test:e2e
+```
+
+## Test Categories
+
+### 1. Navigation Tests
+
+#### Test: Basic Navigation
+- **Step 1**: Load homepage (`/docs`)
+- **Step 2**: Verify title in header
+- **Step 3**: Click navigation link to `/docs/guides`
+- **Step 4**: Verify page content loads
+- **Expected**: Page transitions smoothly, content updates
+
+#### Test: Breadcrumb Navigation
+- **Step 1**: Navigate to `/docs/guides/getting-started`
+- **Step 2**: Verify breadcrumbs show: Home > Docs > Guides > Getting Started
+- **Step 3**: Click on "Guides" breadcrumb
+- **Step 4**: Verify navigation to `/docs/guides`
+- **Expected**: Breadcrumbs work as navigation
+
+#### Test: Sidebar Navigation
+- **Step 1**: Open page with sidebar visible
+- **Step 2**: Verify all navigation items render
+- **Step 3**: Click on a navigation section
+- **Step 4**: Verify active state updates
+- **Expected**: Active item highlighted, content loads
+
+#### Test: Prev/Next Navigation
+- **Step 1**: Navigate to a doc page
+- **Step 2**: Click "Next" button
+- **Step 3**: Verify next document loads
+- **Step 4**: Click "Previous" button
+- **Step 5**: Verify previous document loads
+- **Expected**: Navigation works correctly through document sequence
+
+### 2. Search Tests
+
+#### Test: Basic Search
+- **Step 1**: Click search input
+- **Step 2**: Type "getting started"
+- **Step 3**: Wait for results to load
+- **Step 4**: Verify results display at least one match
+- **Expected**: Search results show relevant pages
+
+#### Test: Search Results Navigation
+- **Step 1**: Perform search for "API"
+- **Step 2**: Click on first search result
+- **Step 3**: Verify page loads and contains "API" in title
+- **Step 4**: Verify search query cleared
+- **Expected**: Clicking result navigates to page
+
+#### Test: Search Highlighting
+- **Step 1**: Search for "authentication"
+- **Step 2**: Navigate to a result
+- **Step 3**: Verify search term is highlighted in content
+- **Expected**: Search terms highlighted with visual indicator
+
+#### Test: No Results
+- **Step 1**: Search for gibberish "xyzabc123notaterm"
+- **Step 2**: Verify "No results found" message displays
+- **Step 3**: Verify suggestion to try different keywords
+- **Expected**: Helpful error message shown
+
+#### Test: Search Pagination
+- **Step 1**: Search for common term with many results
+- **Step 2**: Verify pagination controls appear
+- **Step 3**: Click page 2
+- **Step 4**: Verify different results load
+- **Expected**: Pagination works, page updates
+
+### 3. Dark Mode Tests
+
+#### Test: Dark Mode Toggle
+- **Step 1**: Load page in light mode
+- **Step 2**: Locate dark mode toggle
+- **Step 3**: Click toggle
+- **Step 4**: Verify page switches to dark theme
+- **Step 5**: Verify toggle state updated
+- **Expected**: Dark mode applies instantly
+
+#### Test: Dark Mode Persistence
+- **Step 1**: Enable dark mode
+- **Step 2**: Navigate to different page
+- **Step 3**: Verify dark mode still active
+- **Step 4**: Reload page
+- **Step 5**: Verify dark mode persisted
+- **Expected**: Dark mode preference saved
+
+#### Test: Dark Mode Readability
+- **Step 1**: Enable dark mode
+- **Step 2**: Verify text contrast meets WCAG AA standard
+- **Step 3**: Check code blocks are readable
+- **Step 4**: Verify links are distinguishable
+- **Expected**: Dark mode is readable and accessible
+
+#### Test: System Dark Mode Detection
+- **Step 1**: Set system to dark mode
+- **Step 2**: Load page without preference set
+- **Step 3**: Verify page loads in dark mode
+- **Expected**: Respects system preference
+
+### 4. Responsive Design Tests
+
+#### Test: Mobile Navigation
+- **Step 1**: Resize to mobile (375px width)
+- **Step 2**: Verify hamburger menu appears
+- **Step 3**: Click hamburger menu
+- **Step 4**: Verify sidebar menu opens
+- **Step 5**: Click menu item
+- **Step 6**: Verify menu closes and navigates
+- **Expected**: Mobile menu works correctly
+
+#### Test: Mobile Search
+- **Step 1**: Resize to mobile
+- **Step 2**: Click search icon
+- **Step 3**: Type search query
+- **Step 4**: Verify results display in mobile layout
+- **Expected**: Search works on mobile
+
+#### Test: Tablet Layout
+- **Step 1**: Resize to tablet (768px width)
+- **Step 2**: Verify layout adapts appropriately
+- **Step 3**: Verify sidebar and content visible
+- **Expected**: Tablet layout balanced
+
+#### Test: Desktop Layout
+- **Step 1**: Resize to desktop (1440px)
+- **Step 2**: Verify three-column layout (nav, content, toc)
+- **Step 3**: Verify all elements visible
+- **Expected**: Full desktop layout works
+
+### 5. Content Rendering Tests
+
+#### Test: Markdown Rendering
+- **Step 1**: Navigate to page with various markdown
+- **Step 2**: Verify headers render correctly
+- **Step 3**: Verify lists render correctly
+- **Step 4**: Verify code blocks render correctly
+- **Step 5**: Verify links render correctly
+- **Expected**: All markdown elements render properly
+
+#### Test: Code Block Display
+- **Step 1**: Navigate to page with code blocks
+- **Step 2**: Verify syntax highlighting applied
+- **Step 3**: Verify copy button present
+- **Step 4**: Click copy button
+- **Step 5**: Verify code copied to clipboard
+- **Expected**: Code blocks fully functional
+
+#### Test: Table of Contents
+- **Step 1**: Navigate to page with multiple sections
+- **Step 2**: Verify TOC appears on right sidebar
+- **Step 3**: Click TOC link
+- **Step 4**: Verify page scrolls to section
+- **Expected**: TOC works and smooth scrolls
+
+#### Test: Image Display
+- **Step 1**: Navigate to page with images
+- **Step 2**: Verify images load
+- **Step 3**: Verify captions display
+- **Step 4**: Verify responsive sizing
+- **Expected**: Images display correctly
+
+### 6. Accessibility Tests
+
+#### Test: Keyboard Navigation
+- **Step 1**: Load page
+- **Step 2**: Press Tab to navigate
+- **Step 3**: Verify focus visible on elements
+- **Step 4**: Press Enter on links
+- **Step 5**: Verify navigation works
+- **Expected**: Fully keyboard navigable
+
+#### Test: Screen Reader Support
+- **Step 1**: Load page with screen reader
+- **Step 2**: Verify page structure announced
+- **Step 3**: Verify links have descriptive text
+- **Step 4**: Verify images have alt text
+- **Expected**: Content accessible to screen readers
+
+#### Test: Focus Management
+- **Step 1**: Navigate to new page
+- **Step 2**: Verify focus moves to main content
+- **Step 3**: Skip to main content link works
+- **Expected**: Focus properly managed
+
+#### Test: Color Contrast
+- **Step 1**: Analyze page color contrast
+- **Step 2**: Verify WCAG AA compliance
+- **Step 3**: Check both light and dark modes
+- **Expected**: Sufficient contrast for readability
+
+### 7. Performance Tests
+
+#### Test: Page Load Performance
+- **Step 1**: Measure page load time
+- **Step 2**: Verify LCP (Largest Contentful Paint) < 2.5s
+- **Step 3**: Verify CLS (Cumulative Layout Shift) < 0.1
+- **Expected**: Good Core Web Vitals
+
+#### Test: Search Performance
+- **Step 1**: Perform search
+- **Step 2**: Measure time to results
+- **Step 3**: Verify results within 100ms
+- **Expected**: Search responsive
+
+#### Test: Navigation Performance
+- **Step 1**: Navigate between pages
+- **Step 2**: Measure navigation time
+- **Step 3**: Verify smooth transitions
+- **Expected**: No lag in navigation
+
+### 8. Form and Input Tests
+
+#### Test: Search Form
+- **Step 1**: Click search input
+- **Step 2**: Type and verify input captures text
+- **Step 3**: Clear search
+- **Step 4**: Verify input cleared
+- **Expected**: Search form works
+
+#### Test: Theme Selector
+- **Step 1**: Locate theme selector
+- **Step 2**: Select different theme
+- **Step 3**: Verify theme applied
+- **Expected**: Theme selector functional
+
+### 9. Error Handling Tests
+
+#### Test: 404 Page
+- **Step 1**: Navigate to non-existent page
+- **Step 2**: Verify 404 page displays
+- **Step 3**: Verify helpful message
+- **Step 4**: Verify link to homepage
+- **Expected**: Graceful error handling
+
+#### Test: Offline Handling
+- **Step 1**: Go offline
+- **Step 2**: Try to search
+- **Step 3**: Verify appropriate message
+- **Expected**: Handles offline state
+
+### 10. Cross-browser Tests
+
+#### Test: Chrome/Chromium
+- Run all tests in Chrome
+
+#### Test: Firefox
+- Run all tests in Firefox
+
+#### Test: Safari
+- Run all tests in Safari (macOS)
+
+#### Test: Edge
+- Run all tests in Edge
+
+## Test Configuration
+
+```javascript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: 'html',
+  use: {
+    baseURL: 'http://localhost:5173',
+    trace: 'on-first-retry',
+  },
+
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+    {
+      name: 'Mobile Chrome',
+      use: { ...devices['Pixel 5'] },
+    },
+    {
+      name: 'Mobile Safari',
+      use: { ...devices['iPhone 12'] },
+    },
+  ],
+
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:5173',
+    reuseExistingServer: !process.env.CI,
+  },
+});
+```
+
+## Continuous Integration
+
+E2E tests run in CI pipeline after unit tests pass:
+
+```yaml
+# .github/workflows/test.yml
+- name: Run E2E tests
+  run: npm run test:e2e
+  if: success()
+```
+
+## Coverage Goals
+
+- Navigation: 100%
+- Search: 95%
+- Dark Mode: 90%
+- Accessibility: 90%
+- Performance: 85%
+
+## Known Limitations
+
+- E2E tests depend on stable test environment
+- Tests may be flaky on slow CI systems
+- Search tests depend on Pagefind index being built
+- Offline tests require special network setup
+
+## Future Improvements
+
+- Visual regression testing with Percy or similar
+- Performance budgets and monitoring
+- Automated accessibility scanning
+- Analytics and error tracking tests