super-productivity/e2e

E2E Testing Guide for Super Productivity

This guide provides comprehensive information for writing and maintaining end-to-end tests for Super Productivity using Playwright.

Table of Contents

• Overview
• Running Tests
• Test Structure
• Page Objects
• Common Patterns
• Selectors
• Wait Utilities
• Writing New Tests
• Best Practices
• Troubleshooting

---

Overview

Our E2E tests are built with Playwright and follow the Page Object Model (POM) pattern for maintainability and reusability. Tests are organized by feature and use shared fixtures for common setup.

Key Technologies

• Playwright: Modern E2E testing framework
• TypeScript: Type-safe test code
• Page Object Model: Encapsulates page interactions
• Fixtures: Shared setup and utilities

---

Running Tests

Basic Commands

# Run all tests
npm run e2e

# Run tests in UI mode (interactive)
npm run e2e:ui

# Run a single test file with detailed output
npm run e2e:file tests/task-basic/task-crud.spec.ts

# Run tests in headed mode (see browser)
npm run e2e:headed

# Run tests in debug mode
npm run e2e:debug

# Show test report
npm run e2e:show-report

WebDAV Sync Tests

# Run WebDAV tests (starts Docker container)
npm run e2e:webdav

---

Test Structure

Directory Layout

e2e/
├── constants/          # Shared selectors and constants
│   └── selectors.ts    # Centralized CSS selectors
├── fixtures/           # Test fixtures and setup
│   └── test.fixture.ts # Custom test fixtures with page objects
├── helpers/            # Test helper functions
│   └── plugin-test.helpers.ts
├── pages/              # Page Object Models
│   ├── base.page.ts    # Base page with common methods
│   ├── work-view.page.ts
│   ├── project.page.ts
│   ├── task.page.ts
│   ├── settings.page.ts
│   ├── dialog.page.ts
│   ├── planner.page.ts
│   ├── side-nav.page.ts
│   ├── sync.page.ts
│   ├── tag.page.ts
│   └── note.page.ts
├── tests/              # Test specifications
│   ├── task-basic/
│   ├── project/
│   ├── planner/
│   └── ...
├── utils/              # Utility functions
│   ├── waits.ts        # Wait helpers
│   └── sync-helpers.ts
├── playwright.config.ts
└── global-setup.ts

---

Page Objects

Page Objects encapsulate interactions with specific pages or components. All page objects extend BasePage and receive a page and optional testPrefix.

Available Page Objects

1. BasePage (base.page.ts)

Base class for all page objects. Provides common functionality:

class BasePage {
  async addTask(taskName: string): Promise<void>;
  // Adds a task with automatic test prefix
}

Example:

await workViewPage.addTask('My Task');
// Creates task with name "W0-P0-My Task" (prefixed for isolation)

2. WorkViewPage (work-view.page.ts)

Interactions with the main work view:

class WorkViewPage extends BasePage {
  async waitForTaskList(): Promise<void>;
  async addSubTask(task: Locator, subTaskName: string): Promise<void>;
}

Example:

await workViewPage.waitForTaskList();
await workViewPage.addTask('Parent Task');
const task = page.locator('task').first();
await workViewPage.addSubTask(task, 'Child Task');

3. TaskPage (task.page.ts)

Task-specific operations:

class TaskPage extends BasePage {
  getTask(index: number): Locator;
  getTaskByText(text: string): Locator;
  async markTaskAsDone(task: Locator): Promise<void>;
  async editTaskTitle(task: Locator, newTitle: string): Promise<void>;
  async openTaskDetail(task: Locator): Promise<void>;
  async getTaskCount(): Promise<number>;
  async isTaskDone(task: Locator): Promise<boolean>;
  getDoneTasks(): Locator;
  getUndoneTasks(): Locator;
  async waitForTaskWithText(text: string): Promise<Locator>;
  async taskHasTag(task: Locator, tagName: string): Promise<boolean>;
}

Example:

const task = taskPage.getTask(1); // First task
await taskPage.markTaskAsDone(task);
await expect(taskPage.getDoneTasks()).toHaveCount(1);

4. ProjectPage (project.page.ts)

Project management:

class ProjectPage extends BasePage {
  async createProject(projectName: string): Promise<void>;
  async navigateToProjectByName(projectName: string): Promise<void>;
  async createAndGoToTestProject(): Promise<void>;
  async addNote(noteContent: string): Promise<void>;
  async archiveDoneTasks(): Promise<void>;
}

Example:

await projectPage.createProject('My Project');
await projectPage.navigateToProjectByName('My Project');
await projectPage.addNote('Project notes here');

5. SettingsPage (settings.page.ts)

Settings and configuration:

class SettingsPage extends BasePage {
  async navigateToSettings(): Promise<void>;
  async expandSection(sectionSelector: string): Promise<void>;
  async expandPluginSection(): Promise<void>;
  async navigateToPluginSettings(): Promise<void>;
  async enablePlugin(pluginName: string): Promise<boolean>;
  async disablePlugin(pluginName: string): Promise<boolean>;
  async isPluginEnabled(pluginName: string): Promise<boolean>;
  async uploadPlugin(pluginPath: string): Promise<void>;
}

Example:

await settingsPage.navigateToPluginSettings();
await settingsPage.enablePlugin('Test Plugin');
expect(await settingsPage.isPluginEnabled('Test Plugin')).toBeTruthy();

6. DialogPage (dialog.page.ts)

Dialog and modal interactions:

class DialogPage extends BasePage {
  async waitForDialog(): Promise<Locator>;
  async waitForDialogToClose(): Promise<void>;
  async clickDialogButton(buttonText: string): Promise<void>;
  async clickSaveButton(): Promise<void>;
  async fillDialogInput(selector: string, value: string): Promise<void>;
  async fillMarkdownDialog(content: string): Promise<void>;
  async saveMarkdownDialog(): Promise<void>;
  async editDateTime(dateValue?: string, timeValue?: string): Promise<void>;
}

Example:

await dialogPage.waitForDialog();
await dialogPage.fillDialogInput('input[name="title"]', 'New Title');
await dialogPage.clickSaveButton();
await dialogPage.waitForDialogToClose();

---

Common Patterns

Pattern 1: Basic Task CRUD

test('should create and edit task', async ({ page, workViewPage, taskPage }) => {
  await workViewPage.waitForTaskList();

  // Create
  await workViewPage.addTask('Test Task');
  await expect(taskPage.getAllTasks()).toHaveCount(1);

  // Edit
  const task = taskPage.getTask(1);
  await taskPage.editTaskTitle(task, 'Updated Task');
  await expect(taskPage.getTaskTitle(task)).toContainText('Updated Task');

  // Mark as done
  await taskPage.markTaskAsDone(task);
  await expect(taskPage.getDoneTasks()).toHaveCount(1);
});

Pattern 2: Project Workflow

test('should create project and add tasks', async ({ projectPage, workViewPage }) => {
  await projectPage.createAndGoToTestProject();
  await workViewPage.addTask('Project Task 1');
  await workViewPage.addTask('Project Task 2');
  await expect(page.locator('task')).toHaveCount(2);
});

Pattern 3: Settings Configuration

test('should enable plugin', async ({ settingsPage, waitForNav }) => {
  await settingsPage.navigateToPluginSettings();
  await settingsPage.enablePlugin('My Plugin');
  await waitForNav();
  expect(await settingsPage.isPluginEnabled('My Plugin')).toBeTruthy();
});

Pattern 4: Dialog Interactions

test('should edit date in dialog', async ({ taskPage, dialogPage }) => {
  const task = taskPage.getTask(1);
  await taskPage.openTaskDetail(task);

  const dateInfo = dialogPage.getDateInfo('Created');
  await dateInfo.click();
  await dialogPage.editDateTime('12/25/2025', undefined);
  await dialogPage.clickSaveButton();
});

---

Selectors

All selectors are centralized in constants/selectors.ts. Always use these constants instead of hardcoding selectors in tests.

Using Selectors

import { cssSelectors } from '../constants/selectors';

const { TASK, TASK_TITLE, TASK_DONE_BTN } = cssSelectors;

// In test:
const task = page.locator(TASK).first();
const title = task.locator(TASK_TITLE);

Selector Categories

• Navigation: SIDENAV, NAV_ITEM, SETTINGS_BTN
• Layout: ROUTE_WRAPPER, BACKDROP, PAGE_TITLE
• Tasks: TASK, TASK_TITLE, TASK_DONE_BTN, SUB_TASK
• Add Task: ADD_TASK_INPUT, ADD_TASK_SUBMIT
• Dialogs: MAT_DIALOG, DIALOG_FULLSCREEN_MARKDOWN
• Settings: PAGE_SETTINGS, PLUGIN_SECTION, PLUGIN_MANAGEMENT
• Projects: PAGE_PROJECT, CREATE_PROJECT_BTN, WORK_CONTEXT_MENU

---

Wait Utilities

Located in utils/waits.ts, these utilities help handle Angular's async nature.

Available Wait Functions

waitForAngularStability(page, timeout?)

Waits for Angular to finish all async operations.

await waitForAngularStability(page);

waitForAppReady(page, options?)

Comprehensive wait for app initialization.

await waitForAppReady(page, {
  selector: 'task-list',
  ensureRoute: true,
  routeRegex: /#\/project\/\w+/,
});

waitForStatePersistence(page)

Waits for IndexedDB persistence to complete (important before sync operations).

await workViewPage.addTask('Task');
await waitForStatePersistence(page); // Ensure saved to IndexedDB
// Now safe to trigger sync

---

Writing New Tests

Step 1: Create Test File

// e2e/tests/my-feature/my-feature.spec.ts
import { test, expect } from '../../fixtures/test.fixture';

test.describe('My Feature', () => {
  test('should do something', async ({ page, workViewPage, taskPage }) => {
    // Test code here
  });
});

Step 2: Use Page Objects

test('my test', async ({ workViewPage, taskPage, dialogPage }) => {
  // Wait for page ready
  await workViewPage.waitForTaskList();

  // Use page objects for interactions
  await workViewPage.addTask('Task 1');
  const task = taskPage.getTask(1);
  await taskPage.markTaskAsDone(task);

  // Assertions
  await expect(taskPage.getDoneTasks()).toHaveCount(1);
});

Step 3: Handle Waits Properly

// GOOD: Use Angular stability waits
await workViewPage.addTask('Task');
await waitForAngularStability(page);
await expect(page.locator('task')).toBeVisible();

// BAD: Arbitrary timeouts
await page.waitForTimeout(5000); // Avoid unless necessary

Step 4: Use Selectors from Constants

import { cssSelectors } from '../../constants/selectors';

const { TASK, TASK_TITLE } = cssSelectors;
const title = page.locator(TASK).first().locator(TASK_TITLE);

---

Best Practices

✅ DO

1. Use page objects for all interactions
2. Use centralized selectors from constants/selectors.ts
3. Wait for Angular stability after state changes
4. Use test prefixes (automatic via fixtures) for isolation
5. Test one thing per test - keep tests focused
6. Use descriptive test names - "should create task and mark as done"
7. Clean up state - tests should be independent
8. Use role-based selectors when possible (accessibility)

// GOOD
await page.getByRole('button', { name: 'Save' }).click();

// LESS GOOD
await page.locator('.save-btn').click();

❌ DON'T

1. Don't hardcode selectors - use cssSelectors
2. Don't use arbitrary waits - use waitForAngularStability
3. Don't share state between tests - each test should be independent
4. Don't access DOM directly - use page objects
5. Don't skip error handling - tests should fail clearly
6. Don't use any types - maintain type safety

Test Isolation

Each test gets:

• Isolated browser context (clean storage)
• Unique test prefix (W0-P0-, W1-P0-, etc.)
• Fresh page instance

This ensures tests don't interfere with each other.

Handling Flakiness

// Use waitFor with explicit conditions
await page.waitForFunction(() => document.querySelectorAll('task').length === 3, {
  timeout: 10000,
});

// Use locator assertions (auto-retry)
await expect(page.locator('task')).toHaveCount(3);

// Avoid fixed timeouts
await page.waitForTimeout(1000); // BAD
await waitForAngularStability(page); // GOOD

---

Troubleshooting

Test Fails with "Element not found"

1. Check if selector is correct in constants/selectors.ts
2. Add wait before interaction: await waitForAngularStability(page)
3. Use await element.waitFor({ state: 'visible' })
4. Check if element is in a different context (iframe, shadow DOM)

Test Timeout

1. Increase timeout in specific waitFor calls
2. Check if Angular is stuck - look for pending HTTP requests
3. Use page.pause() to debug interactively
4. Check network tab for failed requests

Flaky Tests

1. Add proper waits: waitForAngularStability, waitForAppReady
2. Avoid page.waitForTimeout() - use condition-based waits
3. Check for race conditions - ensure state is persisted
4. Use waitForStatePersistence before operations that depend on saved state

Debugging

// Pause execution and open Playwright Inspector
await page.pause();

// Take screenshot
await page.screenshot({ path: 'debug.png' });

// Console log page content
console.log(await page.content());

// Get element text for debugging
const text = await page.locator('task').first().textContent();
console.log('Task text:', text);

Running Single Test

# Run specific file
npm run e2e:file tests/task-basic/task-crud.spec.ts

# Run in debug mode
npm run e2e:debug

# Run in headed mode to see browser
npm run e2e:headed

---

Examples

Example 1: Full Task CRUD Test

import { test, expect } from '../../fixtures/test.fixture';

test.describe('Task CRUD', () => {
  test('should create, edit, and delete tasks', async ({
    page,
    workViewPage,
    taskPage,
  }) => {
    await workViewPage.waitForTaskList();

    // Create
    await workViewPage.addTask('Task 1');
    await workViewPage.addTask('Task 2');
    await expect(taskPage.getAllTasks()).toHaveCount(2);

    // Edit
    const firstTask = taskPage.getTask(1);
    await taskPage.editTaskTitle(firstTask, 'Updated Task');
    await expect(taskPage.getTaskTitle(firstTask)).toContainText('Updated Task');

    // Mark as done
    await taskPage.markTaskAsDone(firstTask);
    await expect(taskPage.getDoneTasks()).toHaveCount(1);
    await expect(taskPage.getUndoneTasks()).toHaveCount(1);
  });
});

Example 2: Project Workflow

test('should create project with tasks', async ({
  projectPage,
  workViewPage,
  taskPage,
}) => {
  await projectPage.createAndGoToTestProject();

  await workViewPage.addTask('Project Task');
  await projectPage.addNote('Important notes');

  const task = taskPage.getTask(1);
  await taskPage.markTaskAsDone(task);

  await projectPage.archiveDoneTasks();
  await expect(taskPage.getUndoneTasks()).toHaveCount(0);
});

Example 3: Settings Test

test('should configure plugin', async ({ settingsPage, page }) => {
  await settingsPage.navigateToPluginSettings();

  const pluginExists = await settingsPage.pluginExists('Test Plugin');
  expect(pluginExists).toBeTruthy();

  await settingsPage.enablePlugin('Test Plugin');
  expect(await settingsPage.isPluginEnabled('Test Plugin')).toBeTruthy();

  await settingsPage.navigateBackToWorkView();
  await expect(page).toHaveURL(/tag\/TODAY/);
});

---

Getting Help

• Check existing tests in e2e/tests/ for examples
• Review page objects in e2e/pages/ for available methods
• Look at constants/selectors.ts for available selectors
• Use Playwright Inspector (npm run e2e:debug) for debugging
• Check Playwright docs: https://playwright.dev/

---

Summary Checklist

When writing a new test:

• Create test file in appropriate tests/ subdirectory
• Import test and expect from fixtures/test.fixture.ts
• Use page objects for all interactions
• Use selectors from constants/selectors.ts
• Add proper waits (waitForAngularStability, etc.)
• Use descriptive test names
• Ensure test is isolated (no shared state)
• Run test locally before committing
• Test passes consistently (run 3+ times)