Skip to content

Privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable.

15.7 KB
Raw Blame
/**
 * TestClient - A fluent API wrapper for browser extension E2E testing.

 * Example usage:
 * ```typescript
 * const client = await TestClient.create();
 * await client
 *   .login(apiUrl, username, password)
 *   .createCredential('My Login', 'user@example.com', 'password123')
 *   .verifyCredentialExists('My Login');
 * ```
 */
import type { BrowserContext, Page } from '@playwright/test';

import { createFreshContext, expect, test } from './fixtures';
import { waitForVaultOpen } from './helpers';
import { FieldSelectors, ButtonSelectors } from './selectors';
import {
  waitForVaultReady,
  waitForSyncComplete,
  waitForCredentialSaved,
  waitForSettingsPage,
  waitForUnlockPage,
  waitForOfflineIndicator,
  waitForLoginForm,
  waitForPopupReady,
  Timeouts,
} from './waits';

/**
 * TestClient provides a fluent API for E2E testing of the browser extension.
 */
export class TestClient {
  public context: BrowserContext;
  public extensionId: string;
  public popup: Page;

  private constructor(context: BrowserContext, extensionId: string, popup: Page) {
    this.context = context;
    this.extensionId = extensionId;
    this.popup = popup;
  }

  /**
   * Create a new TestClient with a fresh browser context.
   */
  static async create(): Promise<TestClient> {
    const { context, extensionId } = await createFreshContext();

    // Open popup
    const popup = await context.newPage();
    await popup.goto(`chrome-extension://${extensionId}/popup.html`);
    await waitForPopupReady(popup, Timeouts.MEDIUM);

    return new TestClient(context, extensionId, popup);
  }

  /**
   * Create a TestClient from an existing browser context (for shared fixture tests).
   */
  static async fromContext(context: BrowserContext, extensionId: string): Promise<TestClient> {
    const popup = await context.newPage();
    await popup.goto(`chrome-extension://${extensionId}/popup.html`);
    await waitForPopupReady(popup, Timeouts.MEDIUM);
    return new TestClient(context, extensionId, popup);
  }

  /**
   * Configure the API URL for the extension.
   * Verifies the URL is displayed on the login page after configuration.
   */
  async configureApiUrl(apiUrl: string): Promise<this> {
    // Make sure the popup has settled on the login page before touching the header.
    await waitForPopupReady(this.popup);

    // Use a locator so the button is re-resolved if the app re-renders mid-click.
    await this.popup.locator('button#settings').click();
    await this.popup.selectOption('select', ['custom']);
    await this.popup.fill('input#custom-api-url', apiUrl);
    await this.popup.click('button#back');
    await waitForLoginForm(this.popup);

    // Sanity check: verify the configured URL is displayed on the login page
    // This catches cases where the URL wasn't saved (e.g., debounce issues)
    const displayedUrl = await this.popup.locator('text=' + new URL(apiUrl).host).isVisible({ timeout: 2000 })
      .catch(() => false);
    if (!displayedUrl) {
      throw new Error(`API URL configuration failed: expected "${apiUrl}" to be displayed on login page, but it wasn't. This may indicate the URL was not saved properly.`);
    }

    return this;
  }

  /**
   * Open the login settings page (before authentication).
   */
  async openLoginSettings(): Promise<this> {
    await waitForPopupReady(this.popup);
    const settingsButton = this.popup.locator('button#settings');
    await settingsButton.click();
    await expect(this.popup.locator('select')).toBeVisible();
    return this;
  }

  /**
   * Go back from login settings to login page.
   */
  async backToLogin(): Promise<this> {
    await this.popup.click('button#back');
    await waitForLoginForm(this.popup);
    return this;
  }

  /**
   * Login with username and password.
   */
  async login(apiUrl: string, username: string, password: string): Promise<this> {
    await this.configureApiUrl(apiUrl);
    await this.popup.fill('input[type="text"]', username);
    await this.popup.fill('input[type="password"]', password);
    await this.popup.click('button:has-text("Log in")');
    return this.waitForVaultOpen();
  }

  /**
   * Wait for the vault to open after a login or unlock; fails on the upgrade gate.
   */
  async waitForVaultOpen(timeout: number = Timeouts.LONG): Promise<this> {
    await waitForVaultOpen(this.popup, timeout);
    return this;
  }

  /**
   * Stop here and open the Playwright Inspector to look at the popup, only in a `npm run test:e2e:p` run; a no-op otherwise.
   */
  async pause(): Promise<this> {
    if (!process.env.E2E_PAUSE) {
      return this;
    }
    test.info().setTimeout(0);
    await this.popup.pause();
    return this;
  }

  /**
   * Attempt login without expecting success (for testing invalid credentials).
   */
  async attemptLogin(username: string, password: string): Promise<this> {
    await this.popup.fill('input[type="text"]', username);
    await this.popup.fill('input[type="password"]', password);
    await this.popup.click('button:has-text("Log in")');
    return this;
  }

  /**
   * Clear the login form fields.
   */
  async clearLoginForm(): Promise<this> {
    await this.popup.fill('input[type="text"]', '');
    await this.popup.fill('input[type="password"]', '');
    return this;
  }

  /**
   * Submit login credentials (already filled in form).
   */
  async submitLogin(): Promise<this> {
    await this.popup.click('button:has-text("Log in")');
    return this.waitForVaultOpen();
  }

  /**
   * Fill login form fields without submitting.
   */
  async fillLoginForm(username: string, password: string): Promise<this> {
    await this.popup.fill('input[type="text"]', username);
    await this.popup.fill('input[type="password"]', password);
    return this;
  }

  /**
   * Navigate to the vault tab.
   */
  async goToVault(): Promise<this> {
    await this.popup.locator('#nav-vault').click();
    // Wait for the vault list to be ready (items list or add button visible)
    await this.popup.locator(ButtonSelectors.ADD_NEW_ITEM).waitFor({ state: 'visible', timeout: Timeouts.MEDIUM });
    return this;
  }

  /**
   * Navigate to the settings tab.
   */
  async goToSettings(): Promise<this> {
    await this.popup.locator('button#nav-settings').click();
    await waitForSettingsPage(this.popup);
    return this;
  }

  /**
   * Navigate to root to trigger a fresh sync.
   * Waits for the sync indicator to disappear before returning.
   */
  async triggerSync(): Promise<this> {
    await this.popup.evaluate(() => {
      window.location.href = '/popup.html';
    });
    await this.popup.waitForLoadState('domcontentloaded');
    await waitForSyncComplete(this.popup, Timeouts.LONG);
    return this;
  }

  /**
   * Wait until the local changes are pushed to the server. A save only pushes in the background, so another
   * client syncing right after it can otherwise miss the change.
   */
  async waitForServerSync(timeout: number = Timeouts.LONG): Promise<this> {
    await expect.poll(() => this.popup.evaluate(async () => (await chrome.storage.local.get('isDirty')).isDirty === true), { timeout }).toBe(false);
    return this;
  }

  /**
   * Open the add credential form via the item type dropdown in the header.
   */
  async openAddCredentialForm(typeSelector: string = ButtonSelectors.ADD_ITEM_TYPE_LOGIN): Promise<this> {
    const addButton = this.popup.locator(ButtonSelectors.ADD_NEW_ITEM);
    await expect(addButton).toBeVisible();
    await addButton.click();
    await this.popup.locator(typeSelector).click();
    await expect(this.popup.locator(FieldSelectors.ITEM_NAME)).toBeVisible();
    return this;
  }

  /**
   * Create a new login credential.
   * The new ItemAddEdit page shows all fields directly without an intermediate step.
   */
  async createCredential(name: string, username: string, password: string): Promise<this> {
    await this.openAddCredentialForm();
    // All fields are now visible on the same page (no "Next" step)
    await expect(this.popup.locator(FieldSelectors.LOGIN_USERNAME)).toBeVisible({ timeout: Timeouts.MEDIUM });
    await this.popup.fill(FieldSelectors.ITEM_NAME, name);
    await this.popup.fill(FieldSelectors.LOGIN_USERNAME, username);
    await this.popup.fill(FieldSelectors.LOGIN_PASSWORD, password);
    await this.popup.click(ButtonSelectors.SAVE);
    await waitForCredentialSaved(this.popup, name);
    return this;
  }

  /**
   * Create a new login credential with a URL.
   * This is used for testing credential matching based on URLs.
   */
  async createCredentialWithUrl(name: string, username: string, password: string, url: string): Promise<this> {
    await this.openAddCredentialForm();
    // All fields are now visible on the same page (no "Next" step)
    await expect(this.popup.locator(FieldSelectors.LOGIN_USERNAME)).toBeVisible({ timeout: Timeouts.MEDIUM });
    await this.popup.fill(FieldSelectors.ITEM_NAME, name);
    await this.popup.fill(FieldSelectors.LOGIN_USERNAME, username);
    await this.popup.fill(FieldSelectors.LOGIN_PASSWORD, password);
    await this.popup.fill(FieldSelectors.LOGIN_URL, url);
    await this.popup.click(ButtonSelectors.SAVE);
    await waitForCredentialSaved(this.popup, name);
    return this;
  }

  /**
   * Click on a credential in the vault list.
   */
  async clickCredential(name: string): Promise<this> {
    await this.popup.locator(`text=${name}`).click();
    await this.popup.locator(ButtonSelectors.EDIT_ITEM).waitFor({ state: 'visible', timeout: Timeouts.SHORT });
    return this;
  }

  /**
   * Open the edit form for the currently viewed credential.
   */
  async openEditForm(): Promise<this> {
    const editButton = this.popup.locator(ButtonSelectors.EDIT_ITEM);
    await expect(editButton).toBeVisible({ timeout: Timeouts.SHORT });
    await editButton.click();
    await expect(this.popup.locator(FieldSelectors.LOGIN_USERNAME)).toBeVisible({ timeout: Timeouts.MEDIUM });
    return this;
  }

  /**
   * Switch the item type on the add/edit form.
   */
  async switchItemType(type: 'Login' | 'Alias' | 'CreditCard' | 'Note'): Promise<this> {
    await this.popup.click(ButtonSelectors.ITEM_TYPE_SELECTOR);
    await this.popup.click(`button#item-type-option-${type}`);
    return this;
  }

  /**
   * Fill a field in the credential form.
   */
  async fillField(selector: string, value: string): Promise<this> {
    await this.popup.fill(selector, value);
    return this;
  }

  /**
   * Fill the username field.
   */
  async fillUsername(username: string): Promise<this> {
    return this.fillField(FieldSelectors.LOGIN_USERNAME, username);
  }

  /**
   * Fill the password field.
   */
  async fillPassword(password: string): Promise<this> {
    return this.fillField(FieldSelectors.LOGIN_PASSWORD, password);
  }

  /**
   * Fill the notes field.
   * If the notes section is not visible, opens the add field menu and adds it first.
   */
  async fillNotes(notes: string): Promise<this> {
    // Check if notes field is visible, if not add it via the add field menu
    const notesField = this.popup.locator(FieldSelectors.LOGIN_NOTES);
    const isVisible = await notesField.isVisible().catch(() => false);

    if (!isVisible) {
      // Click the add field menu button (dashed border button)
      const addFieldButton = this.popup.locator(ButtonSelectors.ADD_FIELD_MENU);
      await expect(addFieldButton).toBeVisible({ timeout: Timeouts.SHORT });
      await addFieldButton.click();

      // Wait for menu to appear and click the Notes option
      const notesOption = this.popup.locator('button:has-text("Notes")');
      await expect(notesOption).toBeVisible({ timeout: Timeouts.SHORT });
      await notesOption.click();

      // Wait for notes field to appear
      await expect(this.popup.locator(FieldSelectors.LOGIN_NOTES)).toBeVisible({ timeout: Timeouts.MEDIUM });
    }

    return this.fillField(FieldSelectors.LOGIN_NOTES, notes);
  }

  /**
   * Save the current credential form.
   */
  async saveCredential(): Promise<this> {
    await this.popup.click(ButtonSelectors.SAVE);
    await this.popup.waitForLoadState('domcontentloaded');
    return this;
  }

  /**
   * Get the value of a field in the edit form.
   */
  async getFieldValue(selector: string): Promise<string> {
    return this.popup.locator(selector).inputValue();
  }

  /**
   * Wait for a field to have a specific value.
   * Useful for waiting for sync/merge operations to complete.
   */
  async waitForFieldValue(selector: string, expectedValue: string, timeout: number = Timeouts.LONG): Promise<this> {
    await this.popup.waitForFunction(
      ({ sel, expected }) => {
        const input = document.querySelector(sel) as HTMLInputElement | HTMLTextAreaElement;
        return input?.value === expected;
      },
      { sel: selector, expected: expectedValue },
      { timeout }
    );
    return this;
  }

  /**
   * Verify a credential with the given name is visible in the popup.
   *
   * Called from multiple views (the items list, and the detail/view page right
   * after saving), so it can't be scoped to the items list. Uses .first() so the
   * assertion doesn't trip Playwright strict mode when the name appears more than
   * once - e.g. the current-site suggestion duplicating an item already in the list.
   */
  async verifyCredentialExists(name: string, timeout: number = Timeouts.MEDIUM): Promise<this> {
    await expect(this.popup.locator(`text=${name}`).first()).toBeVisible({ timeout });
    return this;
  }

  /**
   * Verify the vault shows a specific item count.
   */
  async verifyVaultItemCount(count: number): Promise<this> {
    const itemsList = this.popup.locator('ul#items-list > li');
    await expect(itemsList).toHaveCount(count, { timeout: Timeouts.SHORT });
    return this;
  }

  /**
   * Enable offline mode by setting an invalid API URL.
   */
  async enableOfflineMode(): Promise<this> {
    await this.popup.evaluate(() => {
      return new Promise<void>((resolve) => {
        chrome.storage.local.set({ apiUrl: 'http://offline.invalid.localhost:9999' }, () => {
          resolve();
        });
      });
    });
    return this;
  }

  /**
   * Disable offline mode by restoring a valid API URL.
   */
  async disableOfflineMode(apiUrl: string): Promise<this> {
    await this.popup.evaluate((url) => {
      return new Promise<void>((resolve) => {
        chrome.storage.local.set({ apiUrl: url }, () => {
          resolve();
        });
      });
    }, apiUrl);
    return this;
  }

  /**
   * Wait for offline indicator to appear.
   */
  async waitForOffline(timeout: number = Timeouts.MEDIUM): Promise<this> {
    await waitForOfflineIndicator(this.popup, timeout);
    return this;
  }

  /**
   * Lock the vault.
   */
  async lockVault(): Promise<this> {
    await this.goToSettings();
    const lockButton = this.popup.locator('button[title="Lock"]');
    await lockButton.click();
    await waitForUnlockPage(this.popup);
    return this;
  }

  /**
   * Unlock the vault with password.
   */
  async unlockVault(password: string): Promise<this> {
    await this.popup.fill('input#password', password);
    await this.popup.click('button[type="submit"]:has-text("Unlock")');
    return this.waitForVaultOpen();
  }

  /**
   * Take a screenshot.
   */
  async screenshot(filename: string): Promise<this> {
    await this.popup.screenshot({ path: `tests/screenshots/${filename}` });
    return this;
  }

  /**
   * Wait for vault to be ready.
   */
  async waitForVaultReady(timeout: number = Timeouts.MEDIUM): Promise<this> {
    await waitForVaultReady(this.popup, timeout);
    return this;
  }

  /**
   * Clean up resources (close popup and context).
   */
  async cleanup(): Promise<void> {
    await this.popup?.close();
    await this.context?.close();
  }

  /**
   * Static helper to clean up multiple clients.
   */
  static async cleanupAll(...clients: (TestClient | null | undefined)[]): Promise<void> {
    for (const client of clients) {
      if (client) {
        await client.cleanup();
      }
    }
  }
}