This is an automated email from the ASF dual-hosted git repository.
rusackas pushed a commit to branch docs/federate-contributing-links
in repository https://gitbox.apache.org/repos/asf/superset.git
The following commit(s) were added to
refs/heads/docs/federate-contributing-links by this push:
new 3395b27b82 docs: federate linting and testing docs, add UPDATING.md
link
3395b27b82 is described below
commit 3395b27b820f33a1c9b54b78d309169cd9d98148
Author: Evan Rusackas <[email protected]>
AuthorDate: Thu Dec 18 15:33:57 2025 -0800
docs: federate linting and testing docs, add UPDATING.md link
Consolidates scattered documentation into the developer portal:
## Linting Documentation
- Merge LINTING_ARCHITECTURE.md and superset-frontend/LINTING.md
into developer_portal/contributing/howtos.md
- Update frontend style guidelines to reference OXC instead of ESLint
- Delete standalone linting markdown files
## E2E Testing Documentation
- Move superset-frontend/playwright/README.md content to
developer_portal/testing/e2e-testing.md
- Replace placeholder "Coming Soon" content with comprehensive guide
- Delete standalone Playwright README
## Upgrading Documentation
- Add Breaking Changes section to upgrading-superset.mdx
- Link to UPDATING.md for version-specific migration notes
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <[email protected]>
---
LINTING_ARCHITECTURE.md | 121 -----------
docs/developer_portal/contributing/howtos.md | 65 +++++-
.../guidelines/frontend-style-guidelines.md | 3 +-
docs/developer_portal/testing/e2e-testing.md | 215 ++++++++++++++++----
docs/docs/installation/upgrading-superset.mdx | 12 ++
superset-frontend/LINTING.md | 165 ---------------
superset-frontend/playwright/README.md | 225 ---------------------
7 files changed, 254 insertions(+), 552 deletions(-)
diff --git a/LINTING_ARCHITECTURE.md b/LINTING_ARCHITECTURE.md
deleted file mode 100644
index 274f0c2467..0000000000
--- a/LINTING_ARCHITECTURE.md
+++ /dev/null
@@ -1,121 +0,0 @@
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
-# Superset Frontend Linting Architecture
-
-## Overview
-We use a hybrid linting approach combining OXC (fast, standard rules) with
custom AST-based checks for Superset-specific patterns.
-
-## Components
-
-### 1. Primary Linter: OXC
-- **What**: Oxidation Compiler's linter (oxlint)
-- **Handles**: 95% of linting rules (standard ESLint rules, TypeScript, React,
etc.)
-- **Speed**: ~50-100x faster than ESLint
-- **Config**: `oxlint.json`
-
-### 2. Custom Rule Checker
-- **What**: Node.js AST-based script
-- **Handles**: Superset-specific rules:
- - No literal colors (use theme)
- - No FontAwesome icons (use Icons component)
- - No template vars in i18n
-- **Speed**: Fast enough for pre-commit
-- **Script**: `scripts/check-custom-rules.js`
-
-## Developer Workflow
-
-### Local Development
-```bash
-# Fast linting (OXC only)
-npm run lint
-
-# Full linting (OXC + custom rules)
-npm run lint:full
-
-# Auto-fix what's possible
-npm run lint-fix
-```
-
-### Pre-commit
-1. OXC runs first (via `scripts/oxlint.sh`)
-2. Custom rules check runs second (lightweight, AST-based)
-3. Both must pass for commit to succeed
-
-### CI Pipeline
-```yaml
-- name: Lint with OXC
- run: npm run lint
-
-- name: Check custom rules
- run: npm run check:custom-rules
-```
-
-## Why This Architecture?
-
-### ✅ Pros
-1. **No binary distribution issues** - ASF compatible
-2. **Fast performance** - OXC for bulk, lightweight script for custom
-3. **Maintainable** - Custom rules in JavaScript, not Rust
-4. **Flexible** - Can evolve as OXC adds plugin support
-5. **Cacheable** - Both OXC and Node.js are standard tools
-
-### ❌ Cons
-1. **Two tools** - Slightly more complex than single linter
-2. **Duplicate parsing** - Files parsed twice (once by each tool)
-
-### 🔄 Migration Path
-When OXC supports JavaScript plugins:
-1. Convert `check-custom-rules.js` to OXC plugin format
-2. Consolidate back to single tool
-3. Keep same rules and developer experience
-
-## Implementation Checklist
-
-- [x] OXC for standard linting
-- [x] Pre-commit integration
-- [ ] Custom rules script
-- [ ] Combine in npm scripts
-- [ ] Update CI pipeline
-- [ ] Developer documentation
-
-## Performance Targets
-
-| Operation | Target Time | Current |
-|-----------|------------|---------|
-| Pre-commit (changed files) | <2s | ✅ 1.5s |
-| Full lint (all files) | <10s | ✅ 8s |
-| Custom rules check | <5s | 🔄 TBD |
-
-## Caching Strategy
-
-### Local Development
-- OXC: Built-in incremental checking
-- Custom rules: Use file hash cache (similar to pytest cache)
-
-### CI
-- Cache `node_modules` (includes oxlint binary)
-- Cache custom rules results by commit hash
-- Skip unchanged files using git diff
-
-## Future Improvements
-
-1. **When OXC adds plugin support**: Migrate custom rules to OXC plugins
-2. **Consider Biome**: Another Rust-based linter with plugin support
-3. **AST sharing**: Investigate sharing AST between tools to avoid double
parsing
diff --git a/docs/developer_portal/contributing/howtos.md
b/docs/developer_portal/contributing/howtos.md
index c353944d7e..8468b8ca20 100644
--- a/docs/developer_portal/contributing/howtos.md
+++ b/docs/developer_portal/contributing/howtos.md
@@ -342,26 +342,79 @@ ruff check --fix .
Pre-commit hooks run automatically on `git commit` if installed.
-### TypeScript
+### TypeScript / JavaScript
-We use ESLint and Prettier for TypeScript:
+We use a hybrid linting approach combining OXC (Oxidation Compiler) for
standard rules and a custom AST-based checker for Superset-specific patterns.
+
+#### Quick Commands
```bash
cd superset-frontend
-# Run eslint checks
+# Run both OXC and custom rules
+npm run lint:full
+
+# Run OXC linter only (faster for most checks)
npm run lint
+# Fix auto-fixable issues with OXC
+npm run lint-fix
+
+# Run custom rules checker only
+npm run check:custom-rules
+
# Run tsc (typescript) checks
npm run type
-# Fix lint issues
-npm run lint-fix
-
# Format with Prettier
npm run prettier
```
+#### Architecture
+
+The linting system consists of two components:
+
+1. **OXC Linter** (`oxlint`) - A Rust-based linter that's 50-100x faster than
ESLint
+ - Handles all standard JavaScript/TypeScript rules
+ - Configured via `oxlint.json`
+ - Runs via `npm run lint` or `npm run lint-fix`
+
+2. **Custom Rules Checker** - A Node.js AST-based checker for
Superset-specific patterns
+ - Enforces no literal colors (use theme colors)
+ - Prevents FontAwesome usage (use @superset-ui/core Icons)
+ - Validates i18n template usage (no template variables)
+ - Runs via `npm run check:custom-rules`
+
+#### Why This Approach?
+
+- **50-100x faster linting** compared to ESLint for standard rules via OXC
+- **Apache-compatible** - No custom binaries, ASF-friendly
+- **Maintainable** - Custom rules in JavaScript, not Rust
+- **Flexible** - Can evolve as OXC adds plugin support
+
+#### Troubleshooting
+
+**"Plugin 'basic-custom-plugin' not found" Error**
+
+Ensure you're using the explicit config:
+```bash
+npx oxlint --config oxlint.json
+```
+
+**Custom Rules Not Running**
+
+Verify the AST parsing dependencies are installed:
+```bash
+npm ls @babel/parser @babel/traverse glob
+```
+
+#### Adding New Custom Rules
+
+1. Edit `scripts/check-custom-rules.js`
+2. Add a new check function following the AST visitor pattern
+3. Call the function in `processFile()`
+4. Test with `npm run check:custom-rules`
+
## GitHub Ephemeral Environments
For every PR, an ephemeral environment is automatically deployed for testing.
diff --git a/docs/developer_portal/guidelines/frontend-style-guidelines.md
b/docs/developer_portal/guidelines/frontend-style-guidelines.md
index b27cbafb5e..03ab3cfc61 100644
--- a/docs/developer_portal/guidelines/frontend-style-guidelines.md
+++ b/docs/developer_portal/guidelines/frontend-style-guidelines.md
@@ -43,8 +43,9 @@ This is a list of statements that describe how we do frontend
development in Sup
- We organize our repo so similar files live near each other, and tests are
co-located with the files they test.
- See: [SIP-61](https://github.com/apache/superset/issues/12098)
- We prefer small, easily testable files and components.
-- We use ESLint and Prettier to automatically fix lint errors and format the
code.
+- We use OXC (oxlint) and Prettier to automatically fix lint errors and format
the code.
- We do not debate code formatting style in PRs, instead relying on
automated tooling to enforce it.
- If there's not a linting rule, we don't have a rule!
+ - See: [Linting How-Tos](../contributing/howtos#typescript--javascript)
- We use [React Storybook](https://storybook.js.org/) and
[Applitools](https://applitools.com/) to help preview/test and stabilize our
components
- A public Storybook with components from the `master` branch is available
[here](https://apache-superset.github.io/superset-ui/?path=/story/*)
diff --git a/docs/developer_portal/testing/e2e-testing.md
b/docs/developer_portal/testing/e2e-testing.md
index ad0fdd4118..a453612376 100644
--- a/docs/developer_portal/testing/e2e-testing.md
+++ b/docs/developer_portal/testing/e2e-testing.md
@@ -24,57 +24,204 @@ under the License.
# End-to-End Testing
-🚧 **Coming Soon** 🚧
+Apache Superset uses Playwright for end-to-end testing, migrating from the
legacy Cypress tests.
-Guide for writing and running end-to-end tests using Playwright and Cypress.
-
-## Topics to be covered:
+## Running Tests
### Playwright (Recommended)
-- Setting up Playwright environment
-- Writing reliable E2E tests
-- Page Object Model pattern
-- Handling async operations
-- Cross-browser testing
-- Visual regression testing
-- Debugging with Playwright Inspector
-- CI/CD integration
-
-### Cypress (Deprecated)
-- Legacy Cypress test maintenance
-- Migration to Playwright
-- Running existing Cypress tests
-## Quick Commands
-
-### Playwright
```bash
-# Run all Playwright tests
-npm run playwright:test
+cd superset-frontend
-# Run in headed mode (see browser)
-npm run playwright:headed
+# Run all tests
+npm run playwright:test
+# or: npx playwright test
# Run specific test file
npx playwright test tests/auth/login.spec.ts
-# Debug specific test
-npm run playwright:debug tests/auth/login.spec.ts
-
-# Open Playwright UI
+# Run with UI mode for debugging
npm run playwright:ui
+# or: npx playwright test --ui
+
+# Run in headed mode (see browser)
+npm run playwright:headed
+# or: npx playwright test --headed
+
+# Debug specific test file
+npm run playwright:debug tests/auth/login.spec.ts
+# or: npx playwright test --debug tests/auth/login.spec.ts
```
### Cypress (Deprecated)
+
+Cypress tests are being migrated to Playwright. For legacy tests:
+
```bash
-# Run Cypress tests
cd superset-frontend/cypress-base
-npm run cypress-run-chrome
+npm run cypress-run-chrome # Headless
+npm run cypress-debug # Interactive UI
+```
-# Open Cypress UI
-npm run cypress-debug
+## Project Architecture
+
+```
+superset-frontend/playwright/
+├── components/core/ # Reusable UI components
+├── pages/ # Page Object Models
+├── tests/ # Test files organized by feature
+├── utils/ # Shared constants and utilities
+└── playwright.config.ts
```
----
+## Design Principles
+
+We follow **YAGNI** (You Aren't Gonna Need It), **DRY** (Don't Repeat
Yourself), and **KISS** (Keep It Simple, Stupid) principles:
+
+- Build only what's needed now
+- Reuse existing patterns and components
+- Keep solutions simple and maintainable
+
+## Page Object Pattern
+
+Each page object encapsulates:
+
+- **Actions**: What you can do on the page
+- **Queries**: Information you can get from the page
+- **Selectors**: Centralized in private static SELECTORS constant
+- **NO Assertions**: Keep assertions in test files
+
+**Example Page Object:**
+
+```typescript
+export class AuthPage {
+ // Selectors centralized in the page object
+ private static readonly SELECTORS = {
+ LOGIN_FORM: '[data-test="login-form"]',
+ USERNAME_INPUT: '[data-test="username-input"]',
+ } as const;
+
+ // Actions - what you can do
+ async loginWithCredentials(username: string, password: string) {}
+
+ // Queries - information you can get
+ async getCurrentUrl(): Promise<string> {}
+
+ // NO assertions - those belong in tests
+}
+```
+
+**Example Test:**
+
+```typescript
+import { test, expect } from '@playwright/test';
+import { AuthPage } from '../../pages/AuthPage';
+import { LOGIN } from '../../utils/urls';
+
+test('should login with correct credentials', async ({ page }) => {
+ const authPage = new AuthPage(page);
+ await authPage.goto();
+ await authPage.loginWithCredentials('admin', 'general');
+
+ // Assertions belong in tests, not page objects
+ expect(await authPage.getCurrentUrl()).not.toContain(LOGIN);
+});
+```
+
+## Core Components
+
+Reusable UI interaction classes for common elements (`components/core/`):
+
+- **Form**: Container with properly scoped child element access
+- **Input**: Supports `fill()`, `type()`, and `pressSequentially()` methods
+- **Button**: Standard click, hover, focus interactions
+
+**Usage Example:**
+
+```typescript
+import { Form } from '../components/core';
+
+const loginForm = new Form(page, '[data-test="login-form"]');
+const usernameInput = loginForm.getInput('[data-test="username-input"]');
+await usernameInput.fill('admin');
+```
+
+## Test Reports
+
+Playwright generates multiple reports for better visibility:
+
+```bash
+# View interactive HTML report (opens automatically on failure)
+npm run playwright:report
+# or: npx playwright show-report
+
+# View test trace for debugging failures
+npx playwright show-trace test-results/[test-name]/trace.zip
+```
+
+### Report Types
+
+- **List Reporter**: Shows progress and summary table in terminal
+- **HTML Report**: Interactive web interface with screenshots, videos, and
traces
+- **JSON Report**: Machine-readable format in `test-results/results.json`
+- **GitHub Actions**: Annotations in CI for failed tests
+
+### Debugging Failed Tests
+
+When tests fail, Playwright automatically captures:
+
+- **Screenshots** at the point of failure
+- **Videos** of the entire test run
+- **Traces** with timeline and network activity
+- **Error context** with detailed debugging information
+
+All debugging artifacts are available in the HTML report for easy analysis.
+
+## Configuration
+
+- **Config**: `playwright.config.ts` - matches Cypress settings
+- **Base URL**: `http://localhost:8088` (assumes Superset running)
+- **Browsers**: Chrome only for Phase 1 (YAGNI)
+- **Retries**: 2 in CI, 0 locally (matches Cypress)
+
+## Contributing Guidelines
+
+### Adding New Tests
+
+1. **Check existing components** before creating new ones
+2. **Use page objects** for page interactions
+3. **Keep assertions in tests**, not page objects
+4. **Follow naming conventions**: `feature.spec.ts`
+
+### Adding New Components
+
+1. **Follow YAGNI**: Only build what's immediately needed
+2. **Use Locator-based scoping** for proper element isolation
+3. **Support both string selectors and Locator objects** via constructor
overloads
+4. **Add to `components/core/index.ts`** for easy importing
+
+### Adding New Page Objects
+
+1. **Centralize selectors** in private static SELECTORS constant
+2. **Import shared constants** from `utils/urls.ts`
+3. **Actions and queries only** - no assertions
+4. **Use existing components** for DOM interactions
+
+## Migration from Cypress
+
+When porting Cypress tests:
+
+1. **Port the logic**, not the implementation
+2. **Use page objects** instead of inline selectors
+3. **Replace `cy.intercept/cy.wait`** with `page.waitForRequest()`
+4. **Use shared constants** from `utils/urls.ts`
+5. **Follow the established patterns** shown in `tests/auth/login.spec.ts`
+
+## Best Practices
-*This documentation is under active development. Check back soon for updates!*
+- **Centralize selectors** in page objects
+- **Centralize URLs** in `utils/urls.ts`
+- **Use meaningful test descriptions**
+- **Keep page objects action-focused**
+- **Put assertions in tests, not page objects**
+- **Follow the existing patterns** for consistency
diff --git a/docs/docs/installation/upgrading-superset.mdx
b/docs/docs/installation/upgrading-superset.mdx
index 46f00b0616..0cf092a5a0 100644
--- a/docs/docs/installation/upgrading-superset.mdx
+++ b/docs/docs/installation/upgrading-superset.mdx
@@ -47,3 +47,15 @@ superset init
While upgrading superset should not delete your charts and dashboards, we
recommend following best
practices and to backup your metadata database before upgrading. Before
upgrading production, we
recommend upgrading in a staging environment and upgrading production finally
during off-peak usage.
+
+## Breaking Changes
+
+For a detailed list of breaking changes and migration notes for each version,
see
+[UPDATING.md](https://github.com/apache/superset/blob/master/UPDATING.md).
+
+This file documents backwards-incompatible changes and provides guidance for
migrating between
+major versions, including:
+- Configuration changes
+- API changes
+- Database migrations
+- Deprecated features
diff --git a/superset-frontend/LINTING.md b/superset-frontend/LINTING.md
deleted file mode 100644
index 5c9278a446..0000000000
--- a/superset-frontend/LINTING.md
+++ /dev/null
@@ -1,165 +0,0 @@
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
-# Superset Frontend Linting
-
-Apache Superset uses a hybrid linting approach combining OXC (Oxidation
Compiler) for standard rules and a custom AST-based checker for
Superset-specific rules.
-
-## Architecture
-
-The linting system consists of two components:
-
-1. **OXC Linter** (`oxlint`) - A Rust-based linter that's 50-100x faster than
ESLint
- - Handles all standard JavaScript/TypeScript rules
- - Configured via `oxlint.json`
- - Runs via `npm run lint` or `npm run lint-fix`
-
-2. **Custom Rules Checker** - A Node.js AST-based checker for
Superset-specific patterns
- - Enforces no literal colors (use theme colors)
- - Prevents FontAwesome usage (use @superset-ui/core Icons)
- - Validates i18n template usage (no template variables)
- - Runs via `npm run check:custom-rules`
-
-## Usage
-
-### Quick Commands
-
-```bash
-# Run both OXC and custom rules
-npm run lint:full
-
-# Run OXC linter only (faster for most checks)
-npm run lint
-
-# Fix auto-fixable issues with OXC
-npm run lint-fix
-
-# Run custom rules checker only
-npm run check:custom-rules
-
-# Run on specific files
-npm run lint-fix src/components/Button/index.tsx
-npm run check:custom-rules src/theme/*.tsx
-```
-
-### Pre-commit Hooks
-
-The linting system is integrated with pre-commit hooks:
-
-```bash
-# Install pre-commit hooks
-pre-commit install
-
-# Run hooks manually on staged files
-pre-commit run
-
-# Run on specific files
-pre-commit run --files superset-frontend/src/file.tsx
-```
-
-## Configuration
-
-### OXC Configuration (`oxlint.json`)
-
-The OXC configuration includes:
-
-- Standard ESLint rules
-- React and React Hooks rules
-- TypeScript rules
-- Import/export rules
-- JSX accessibility rules
-- Unicorn rules for additional coverage
-
-### Custom Rules
-
-The custom rules are implemented in `scripts/check-custom-rules.js` and check
for:
-
-1. **No Literal Colors**: Enforces using theme colors instead of hardcoded
hex/rgb values
-2. **No FontAwesome**: Requires using `@superset-ui/core` Icons component
-3. **Proper i18n Usage**: Prevents template variables in translation functions
-
-## Performance
-
-The hybrid approach provides:
-
-- **50-100x faster linting** compared to ESLint for standard rules via OXC
-- **Selective checking** - custom rules only run on changed files during
pre-commit
-- **Parallel execution** - OXC and custom rules can run concurrently
-
-## Troubleshooting
-
-### "Plugin 'basic-custom-plugin' not found" Error
-
-If you see this error when running `npm run lint`, ensure you're using the
explicit config:
-
-```bash
-npx oxlint --config oxlint.json
-```
-
-### Custom Rules Not Running
-
-Verify the AST parsing dependencies are installed:
-
-```bash
-npm ls @babel/parser @babel/traverse glob
-```
-
-### Pre-commit Hook Failures
-
-Ensure your changes are staged:
-
-```bash
-git add .
-pre-commit run
-```
-
-## Development
-
-### Adding New Custom Rules
-
-1. Edit `scripts/check-custom-rules.js`
-2. Add a new check function following the pattern:
-
-```javascript
-function checkNewRule(ast, filepath) {
- traverse(ast, {
- // AST visitor pattern
- });
-}
-```
-
-3. Call the function in `processFile()`
-
-### Updating OXC Rules
-
-1. Edit `oxlint.json`
-2. Test with `npm run lint`
-3. Update ignore patterns if needed
-
-## Migration from ESLint
-
-This hybrid approach replaces the previous ESLint setup while maintaining all
custom Superset linting rules. The migration provides:
-
-- Significantly faster linting (50-100x improvement)
-- Compatibility with Apache Software Foundation requirements (no custom
binaries)
-- Maintainable JavaScript-based custom rules
-
-## CI/CD Integration
-
-The linting system is integrated into CI via GitHub Actions. See
`.github/workflows/superset-frontend-lint.yml` for the CI configuration.
diff --git a/superset-frontend/playwright/README.md
b/superset-frontend/playwright/README.md
deleted file mode 100644
index c6d93e8800..0000000000
--- a/superset-frontend/playwright/README.md
+++ /dev/null
@@ -1,225 +0,0 @@
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
-# Playwright E2E Tests for Superset
-
-This directory contains Playwright end-to-end tests for Apache Superset,
designed as a replacement for the existing Cypress tests during the migration
to Playwright.
-
-## Architecture
-
-```
-playwright/
-├── components/core/ # Reusable UI components
-├── pages/ # Page Object Models
-├── tests/ # Test files organized by feature
-├── utils/ # Shared constants and utilities
-└── README.md # This file
-```
-
-## Design Principles
-
-We follow **YAGNI** (You Aren't Gonna Need It), **DRY** (Don't Repeat
Yourself), and **KISS** (Keep It Simple, Stupid) principles:
-
-- Build only what's needed now
-- Reuse existing patterns and components
-- Keep solutions simple and maintainable
-
-## Component Architecture
-
-### Core Components (`components/core/`)
-
-Reusable UI interaction classes for common elements:
-
-- **Form**: Container with properly scoped child element access
-- **Input**: Supports `fill()`, `type()`, and `pressSequentially()` methods
-- **Button**: Standard click, hover, focus interactions
-
-**Usage Example:**
-
-```typescript
-import { Form } from '../components/core';
-
-const loginForm = new Form(page, '[data-test="login-form"]');
-const usernameInput = loginForm.getInput('[data-test="username-input"]');
-await usernameInput.fill('admin');
-```
-
-### Page Objects (`pages/`)
-
-Each page object encapsulates:
-
-- **Actions**: What you can do on the page
-- **Queries**: Information you can get from the page
-- **Selectors**: Centralized in private static SELECTORS constant
-- **NO Assertions**: Keep assertions in test files
-
-**Page Object Pattern:**
-
-```typescript
-export class AuthPage {
- // Selectors centralized in the page object
- private static readonly SELECTORS = {
- LOGIN_FORM: '[data-test="login-form"]',
- USERNAME_INPUT: '[data-test="username-input"]',
- } as const;
-
- // Actions - what you can do
- async loginWithCredentials(username: string, password: string) {}
-
- // Queries - information you can get
- async getCurrentUrl(): Promise<string> {}
-
- // NO assertions - those belong in tests
-}
-```
-
-### Tests (`tests/`)
-
-Organized by feature/area (auth, dashboard, charts, etc.):
-
-- Use page objects for actions
-- Keep assertions in test files
-- Import shared constants from `utils/`
-
-**Test Pattern:**
-
-```typescript
-import { test, expect } from '@playwright/test';
-import { AuthPage } from '../../pages/AuthPage';
-import { LOGIN } from '../../utils/urls';
-
-test('should login with correct credentials', async ({ page }) => {
- const authPage = new AuthPage(page);
- await authPage.goto();
- await authPage.loginWithCredentials('admin', 'general');
-
- // Assertions belong in tests, not page objects
- expect(await authPage.getCurrentUrl()).not.toContain(LOGIN);
-});
-```
-
-### Utilities (`utils/`)
-
-Shared constants and utilities:
-
-- **urls.ts**: URL paths and request patterns
-- Keep flat exports (no premature namespacing)
-
-## Contributing Guidelines
-
-### Adding New Tests
-
-1. **Check existing components** before creating new ones
-2. **Use page objects** for page interactions
-3. **Keep assertions in tests**, not page objects
-4. **Follow naming conventions**: `feature.spec.ts`
-
-### Adding New Components
-
-1. **Follow YAGNI**: Only build what's immediately needed
-2. **Use Locator-based scoping** for proper element isolation
-3. **Support both string selectors and Locator objects** via constructor
overloads
-4. **Add to `components/core/index.ts`** for easy importing
-
-### Adding New Page Objects
-
-1. **Centralize selectors** in private static SELECTORS constant
-2. **Import shared constants** from `utils/urls.ts`
-3. **Actions and queries only** - no assertions
-4. **Use existing components** for DOM interactions
-
-## Running Tests
-
-```bash
-# Run all tests
-npm run playwright:test
-# or: npx playwright test
-
-# Run specific test file
-npx playwright test tests/auth/login.spec.ts
-
-# Run with UI mode for debugging
-npm run playwright:ui
-# or: npx playwright test --ui
-
-# Run in headed mode (see browser)
-npm run playwright:headed
-# or: npx playwright test --headed
-
-# Debug specific test file
-npm run playwright:debug tests/auth/login.spec.ts
-# or: npx playwright test --debug tests/auth/login.spec.ts
-```
-
-## Test Reports
-
-Playwright generates multiple reports for better visibility:
-
-```bash
-# View interactive HTML report (opens automatically on failure)
-npm run playwright:report
-# or: npx playwright show-report
-
-# View test trace for debugging failures
-npx playwright show-trace test-results/[test-name]/trace.zip
-```
-
-### Report Types
-
-- **List Reporter**: Shows progress and summary table in terminal
-- **HTML Report**: Interactive web interface with screenshots, videos, and
traces
-- **JSON Report**: Machine-readable format in `test-results/results.json`
-- **GitHub Actions**: Annotations in CI for failed tests
-
-### Debugging Failed Tests
-
-When tests fail, Playwright automatically captures:
-
-- **Screenshots** at the point of failure
-- **Videos** of the entire test run
-- **Traces** with timeline and network activity
-- **Error context** with detailed debugging information
-
-All debugging artifacts are available in the HTML report for easy analysis.
-
-## Configuration
-
-- **Config**: `playwright.config.ts` - matches Cypress settings
-- **Base URL**: `http://localhost:8088` (assumes Superset running)
-- **Browsers**: Chrome only for Phase 1 (YAGNI)
-- **Retries**: 2 in CI, 0 locally (matches Cypress)
-
-## Migration from Cypress
-
-When porting Cypress tests:
-
-1. **Port the logic**, not the implementation
-2. **Use page objects** instead of inline selectors
-3. **Replace `cy.intercept/cy.wait`** with `page.waitForRequest()`
-4. **Use shared constants** from `utils/urls.ts`
-5. **Follow the established patterns** shown in `tests/auth/login.spec.ts`
-
-## Best Practices
-
-- **Centralize selectors** in page objects
-- **Centralize URLs** in `utils/urls.ts`
-- **Use meaningful test descriptions**
-- **Keep page objects action-focused**
-- **Put assertions in tests, not page objects**
-- **Follow the existing patterns** for consistency
