Add Playwright testing infrastructure for Cesium UI

rdhyee · claude · rdhyee · commit 4eed43dcac7f · 2025-10-31T14:48:43.000-07:00
Establish comprehensive testing foundation for future UI evolution: **Test Framework**: - Playwright for E2E browser testing - Configured for Chromium (extensible to Firefox/Safari) - HTML reporting with traces and screenshots - CI-ready with automatic retries **Test Coverage** (`tests/playwright/cesium-queries.spec.js`): - ✅ Page loading and geocode search box - ✅ Camera movement on geocode search - ✅ HTML table structure (5 columns: Thumbnail | Sample | Description | Site | Location) - ✅ Clickable sample PID links to OpenContext - ✅ "View site" links - ✅ Thumbnail images and "No image" placeholders - ✅ Result count displays - ✅ Empty state friendly messages - ✅ Scrollable tables with sticky headers - ✅ Zebra-striped rows - ✅ Visual consistency across all three tables **Test Data**: - PKAP location with samples: `geoloc_04d6e816218b1a8798fa90b3d1d43bf4c043a57f` - Larnaka site marker (empty state): `geoloc_7a05216d388682536f3e2abd8bd2ee3fb286e461` **Infrastructure Files**: - `playwright.config.js`: Test configuration with extended timeouts - `package.json`: NPM scripts (test, test:headed, test:ui, test:debug) - `tests/README.md`: Comprehensive testing guide - `tests/playwright/cesium-queries.spec.js`: Full test suite **NPM Scripts**: ```bash npm test # Run all tests npm run test:headed # Run with browser visible npm run test:ui # Interactive UI mode npm run test:debug # Debug mode with inspector npm run test:report # View HTML report ``` **Gitignore Updates**: - node_modules/ - test-results/ - playwright-report/ - package-lock.json **Future-Ready**: This infrastructure provides a solid foundation for: - Adding new UI feature tests - Visual regression testing - Accessibility testing - Performance monitoring - Cross-browser testing - Mobile responsive tests Tests validate the enhanced query UI (Path 1, Path 2, Eric's query) to ensure consistent, high-quality user experience as the UI evolves. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/.gitignore b/.gitignore
@@ -6,6 +6,14 @@ docs
 # Large data files
 *.parquet
 
+# Node / Playwright
+node_modules/
+package-lock.json
+tests/playwright-report/
+test-results/
+playwright-report/
+playwright/.cache/
+
 .$*
 
 # Byte-compiled / optimized / DLL files
diff --git a/package.json b/package.json
@@ -0,0 +1,24 @@
+{
+  "name": "isamplesorg-website",
+  "version": "1.0.0",
+  "description": "iSamples website testing infrastructure",
+  "private": true,
+  "scripts": {
+    "test": "playwright test",
+    "test:headed": "playwright test --headed",
+    "test:ui": "playwright test --ui",
+    "test:debug": "playwright test --debug",
+    "test:report": "playwright show-report tests/playwright-report",
+    "test:install": "playwright install chromium"
+  },
+  "keywords": [
+    "isamples",
+    "testing",
+    "playwright"
+  ],
+  "author": "iSamples Team",
+  "license": "MIT",
+  "devDependencies": {
+    "@playwright/test": "^1.40.0"
+  }
+}
diff --git a/playwright.config.js b/playwright.config.js
@@ -0,0 +1,85 @@
+// @ts-check
+const { defineConfig, devices } = require('@playwright/test');
+
+/**
+ * Playwright Configuration for iSamples Cesium Tutorial Tests
+ *
+ * @see https://playwright.dev/docs/test-configuration
+ */
+module.exports = defineConfig({
+  testDir: './tests/playwright',
+
+  /* Run tests in files in parallel */
+  fullyParallel: false,
+
+  /* Fail the build on CI if you accidentally left test.only in the source code. */
+  forbidOnly: !!process.env.CI,
+
+  /* Retry on CI only */
+  retries: process.env.CI ? 2 : 0,
+
+  /* Opt out of parallel tests on CI. */
+  workers: process.env.CI ? 1 : undefined,
+
+  /* Reporter to use. See https://playwright.dev/docs/test-reporters */
+  reporter: [
+    ['html', { outputFolder: 'tests/playwright-report' }],
+    ['list']
+  ],
+
+  /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
+  use: {
+    /* Base URL to use in actions like `await page.goto('/')`. */
+    baseURL: process.env.TEST_URL || 'http://localhost:5860',
+
+    /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
+    trace: 'on-first-retry',
+
+    /* Screenshot on failure */
+    screenshot: 'only-on-failure',
+
+    /* Video on failure */
+    video: 'retain-on-failure',
+
+    /* Extend timeout for slow remote parquet loading */
+    actionTimeout: 15000,
+    navigationTimeout: 60000,
+  },
+
+  /* Configure projects for major browsers */
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+
+    // Uncomment to test on other browsers
+    // {
+    //   name: 'firefox',
+    //   use: { ...devices['Desktop Firefox'] },
+    // },
+    //
+    // {
+    //   name: 'webkit',
+    //   use: { ...devices['Desktop Safari'] },
+    // },
+
+    /* Test against mobile viewports. */
+    // {
+    //   name: 'Mobile Chrome',
+    //   use: { ...devices['Pixel 5'] },
+    // },
+    // {
+    //   name: 'Mobile Safari',
+    //   use: { ...devices['iPhone 12'] },
+    // },
+  ],
+
+  /* Run your local dev server before starting the tests */
+  // webServer: {
+  //   command: 'quarto preview tutorials/parquet_cesium.qmd --no-browser',
+  //   url: 'http://localhost:5860',
+  //   timeout: 120 * 1000,
+  //   reuseExistingServer: !process.env.CI,
+  // },
+});
diff --git a/tests/README.md b/tests/README.md
@@ -0,0 +1,248 @@
+# iSamples Testing Infrastructure
+
+Automated tests for the iSamples Cesium tutorial UI using Playwright.
+
+## Setup
+
+### Install Dependencies
+
+```bash
+npm install
+npx playwright install chromium
+```
+
+### Start Development Server
+
+Before running tests, start the Quarto preview server:
+
+```bash
+quarto preview tutorials/parquet_cesium.qmd --no-browser
+```
+
+This will typically start on `http://localhost:5860` (port may vary).
+
+## Running Tests
+
+### Run All Tests
+
+```bash
+npx playwright test
+```
+
+### Run Specific Test File
+
+```bash
+npx playwright test tests/playwright/cesium-queries.spec.js
+```
+
+### Run in UI Mode (Interactive)
+
+```bash
+npx playwright test --ui
+```
+
+### Run with Browser Visible
+
+```bash
+npx playwright test --headed
+```
+
+### Run Specific Test
+
+```bash
+npx playwright test -g "shows HTML table"
+```
+
+## Test Structure
+
+```
+tests/
+├── playwright/
+│   └── cesium-queries.spec.js   # Cesium UI tests
+└── README.md                     # This file
+```
+
+## What's Tested
+
+### Cesium Query Results UI (`cesium-queries.spec.js`)
+
+Tests the HTML table UI for all three query paths:
+
+1. **Eric's Query** (Path 1 only, authoritative)
+2. **Path 1 Query** (direct event location)
+3. **Path 2 Query** (via site location)
+
+#### Test Coverage
+
+- ✅ Page loads and shows geocode search box
+- ✅ Geocode search triggers camera movement
+- ✅ HTML tables render with correct 5-column structure
+- ✅ Tables contain clickable sample PID links
+- ✅ Tables contain "View site" links
+- ✅ Tables show thumbnails or "No image" placeholders
+- ✅ Result counts display correctly
+- ✅ Empty states show friendly messages
+- ✅ Tables are scrollable with sticky headers
+- ✅ Zebra-striped rows for readability
+- ✅ Visual consistency across all three tables
+
+#### Test Data
+
+**Location with samples** (PKAP):
+- `geoloc_04d6e816218b1a8798fa90b3d1d43bf4c043a57f`
+- Returns ~5 samples via Path 1
+
+**Location without samples** (Larnaka site marker):
+- `geoloc_7a05216d388682536f3e2abd8bd2ee3fb286e461`
+- Returns 0 samples (tests empty state)
+
+## Test Reports
+
+After running tests, view the HTML report:
+
+```bash
+npx playwright show-report tests/playwright-report
+```
+
+## Debugging
+
+### Take Screenshots
+
+Tests automatically capture screenshots on failure.
+
+### View Traces
+
+For failed tests with retries:
+
+```bash
+npx playwright show-trace tests/playwright-report/trace.zip
+```
+
+### Debug Mode
+
+Run tests in debug mode with Playwright Inspector:
+
+```bash
+npx playwright test --debug
+```
+
+## Configuration
+
+Test configuration is in `playwright.config.js`:
+
+- **Test directory**: `./tests/playwright`
+- **Base URL**: `http://localhost:5860` (configurable via `TEST_URL` env var)
+- **Timeouts**: Extended for remote parquet loading
+- **Reporters**: HTML + list
+- **Screenshots**: On failure
+- **Video**: On failure
+
+### Environment Variables
+
+Set custom test URL:
+
+```bash
+TEST_URL=http://localhost:3000 npx playwright test
+```
+
+## Continuous Integration
+
+Tests are designed to run on CI with:
+
+```bash
+# Start Quarto preview in background
+quarto preview tutorials/parquet_cesium.qmd --no-browser &
+
+# Wait for server to start
+sleep 10
+
+# Run tests
+npx playwright test
+
+# CI will automatically retry failed tests 2x
+```
+
+## Adding New Tests
+
+### Test File Template
+
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test.describe('Feature Name', () => {
+
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/tutorials/parquet_cesium.html');
+    // Add setup code
+  });
+
+  test('should do something', async ({ page }) => {
+    // Test code
+    await expect(page.locator('selector')).toBeVisible();
+  });
+});
+```
+
+### Best Practices
+
+1. **Use descriptive test names** - "Table shows result counts" not "test 1"
+2. **Wait for data loading** - Remote parquet queries can be slow
+3. **Test user workflows** - Not implementation details
+4. **Use `test.describe` blocks** - Group related tests
+5. **Keep tests independent** - Each test should work alone
+6. **Use page objects** - For complex selectors (future enhancement)
+
+## Known Issues
+
+### Remote Parquet Loading
+
+The remote parquet file (~700MB) can take time to load. Tests include generous timeouts:
+
+- Action timeout: 15 seconds
+- Navigation timeout: 60 seconds
+- Additional `waitForTimeout` calls where needed
+
+### Observable Cell Evaluation
+
+Observable cells may not evaluate immediately after page load. Tests wait for specific UI elements before interacting.
+
+## Future Enhancements
+
+- [ ] Add visual regression tests (screenshots comparison)
+- [ ] Test mobile responsive layouts
+- [ ] Test keyboard navigation
+- [ ] Test accessibility (ARIA labels, screen readers)
+- [ ] Add performance metrics (query execution time)
+- [ ] Page object pattern for cleaner test code
+- [ ] API mocking to speed up tests (mock parquet responses)
+- [ ] Cross-browser testing (Firefox, Safari)
+
+## Maintenance
+
+### Updating Test Data
+
+If test geocode IDs change, update constants in `cesium-queries.spec.js`:
+
+```javascript
+const TEST_GEOCODE_WITH_SAMPLES = 'geoloc_...';
+const TEST_GEOCODE_NO_SAMPLES = 'geoloc_...';
+```
+
+### Updating Selectors
+
+If UI structure changes, update locators in tests:
+
+```javascript
+// Before
+page.locator('text=Old Label')
+
+// After
+page.locator('text=New Label')
+```
+
+## Resources
+
+- [Playwright Documentation](https://playwright.dev/)
+- [Playwright Test API](https://playwright.dev/docs/api/class-test)
+- [Playwright Best Practices](https://playwright.dev/docs/best-practices)
+- [Quarto Documentation](https://quarto.org/)
diff --git a/tests/playwright/cesium-queries.spec.js b/tests/playwright/cesium-queries.spec.js
