superset2/docs/developer_docs/testing/e2e-testing.md

---
title: End-to-End Testing
sidebar_position: 4
---

<!--
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.
-->

# End-to-End Testing

Apache Superset uses Playwright for end-to-end testing, migrating from the legacy Cypress tests.

## Running Tests

### Playwright (Recommended)

```bash
cd superset-frontend

# 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
```

### Cypress (Deprecated)

Cypress tests are being migrated to Playwright. For legacy tests:

```bash
cd superset-frontend/cypress-base
npm run cypress-run-chrome    # Headless
npm run cypress-debug         # Interactive UI
```

## 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

- **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