refactor: restructure test utilities and enhance context view tests

- Refactored test utilities by consolidating and organizing helper functions into dedicated modules for better maintainability and clarity.
- Introduced new utility functions for interactions, waiting, and element retrieval, improving the readability of test cases.
- Updated context view tests to utilize the new utility functions, enhancing test reliability and reducing code duplication.
- Removed deprecated utility functions and ensured all tests are aligned with the new structure.

apps/app/tests/utils/views/agent.ts

@@ -0,0 +1,98 @@
+import { Page, Locator } from "@playwright/test";
+import { waitForElement } from "../core/waiting";
+
+/**
+ * Get the session list element
+ */
+export async function getSessionList(page: Page): Promise<Locator> {
+  return page.locator('[data-testid="session-list"]');
+}
+
+/**
+ * Get the new session button
+ */
+export async function getNewSessionButton(page: Page): Promise<Locator> {
+  return page.locator('[data-testid="new-session-button"]');
+}
+
+/**
+ * Click the new session button
+ */
+export async function clickNewSessionButton(page: Page): Promise<void> {
+  const button = await getNewSessionButton(page);
+  await button.click();
+}
+
+/**
+ * Get a session item by its ID
+ */
+export async function getSessionItem(
+  page: Page,
+  sessionId: string
+): Promise<Locator> {
+  return page.locator(`[data-testid="session-item-${sessionId}"]`);
+}
+
+/**
+ * Click the archive button for a session
+ */
+export async function clickArchiveSession(
+  page: Page,
+  sessionId: string
+): Promise<void> {
+  const button = page.locator(`[data-testid="archive-session-${sessionId}"]`);
+  await button.click();
+}
+
+/**
+ * Check if the no session placeholder is visible
+ */
+export async function isNoSessionPlaceholderVisible(
+  page: Page
+): Promise<boolean> {
+  const placeholder = page.locator('[data-testid="no-session-placeholder"]');
+  return await placeholder.isVisible();
+}
+
+/**
+ * Wait for the no session placeholder to be visible
+ */
+export async function waitForNoSessionPlaceholder(
+  page: Page,
+  options?: { timeout?: number }
+): Promise<Locator> {
+  return await waitForElement(page, "no-session-placeholder", options);
+}
+
+/**
+ * Check if the message list is visible (indicates a session is selected)
+ */
+export async function isMessageListVisible(page: Page): Promise<boolean> {
+  const messageList = page.locator('[data-testid="message-list"]');
+  return await messageList.isVisible();
+}
+
+/**
+ * Count the number of session items in the session list
+ */
+export async function countSessionItems(page: Page): Promise<number> {
+  const sessionList = page.locator(
+    '[data-testid="session-list"] [data-testid^="session-item-"]'
+  );
+  return await sessionList.count();
+}
+
+/**
+ * Wait for a new session to be created (by checking if a session item appears)
+ */
+export async function waitForNewSession(
+  page: Page,
+  options?: { timeout?: number }
+): Promise<void> {
+  // Wait for any session item to appear
+  const sessionItem = page.locator('[data-testid^="session-item-"]').first();
+  await sessionItem.waitFor({
+    timeout: options?.timeout ?? 5000,
+    state: "visible",
+  });
+}

apps/app/tests/utils/views/board.ts

@@ -0,0 +1,112 @@
+import { Page, Locator } from "@playwright/test";
+
+/**
+ * Get a kanban card by feature ID
+ */
+export async function getKanbanCard(
+  page: Page,
+  featureId: string
+): Promise<Locator> {
+  return page.locator(`[data-testid="kanban-card-${featureId}"]`);
+}
+
+/**
+ * Get a kanban column by its ID
+ */
+export async function getKanbanColumn(
+  page: Page,
+  columnId: string
+): Promise<Locator> {
+  return page.locator(`[data-testid="kanban-column-${columnId}"]`);
+}
+
+/**
+ * Get the width of a kanban column
+ */
+export async function getKanbanColumnWidth(
+  page: Page,
+  columnId: string
+): Promise<number> {
+  const column = page.locator(`[data-testid="kanban-column-${columnId}"]`);
+  const box = await column.boundingBox();
+  return box?.width ?? 0;
+}
+
+/**
+ * Check if a kanban column has CSS columns (masonry) layout
+ */
+export async function hasKanbanColumnMasonryLayout(
+  page: Page,
+  columnId: string
+): Promise<boolean> {
+  const column = page.locator(`[data-testid="kanban-column-${columnId}"]`);
+  const contentDiv = column.locator("> div").nth(1); // Second child is the content area
+
+  const columnCount = await contentDiv.evaluate((el) => {
+    const style = window.getComputedStyle(el);
+    return style.columnCount;
+  });
+
+  return columnCount === "2";
+}
+
+/**
+ * Drag a kanban card from one column to another
+ */
+export async function dragKanbanCard(
+  page: Page,
+  featureId: string,
+  targetColumnId: string
+): Promise<void> {
+  const card = page.locator(`[data-testid="kanban-card-${featureId}"]`);
+  const dragHandle = page.locator(`[data-testid="drag-handle-${featureId}"]`);
+  const targetColumn = page.locator(
+    `[data-testid="kanban-column-${targetColumnId}"]`
+  );
+
+  // Perform drag and drop
+  await dragHandle.dragTo(targetColumn);
+}
+
+/**
+ * Click the view output button on a kanban card
+ */
+export async function clickViewOutput(
+  page: Page,
+  featureId: string
+): Promise<void> {
+  // Try the running version first, then the in-progress version
+  const runningBtn = page.locator(`[data-testid="view-output-${featureId}"]`);
+  const inProgressBtn = page.locator(
+    `[data-testid="view-output-inprogress-${featureId}"]`
+  );
+
+  if (await runningBtn.isVisible()) {
+    await runningBtn.click();
+  } else if (await inProgressBtn.isVisible()) {
+    await inProgressBtn.click();
+  } else {
+    throw new Error(`View output button not found for feature ${featureId}`);
+  }
+}
+
+/**
+ * Check if the drag handle is visible for a specific feature card
+ */
+export async function isDragHandleVisibleForFeature(
+  page: Page,
+  featureId: string
+): Promise<boolean> {
+  const dragHandle = page.locator(`[data-testid="drag-handle-${featureId}"]`);
+  return await dragHandle.isVisible().catch(() => false);
+}
+
+/**
+ * Get the drag handle element for a specific feature card
+ */
+export async function getDragHandleForFeature(
+  page: Page,
+  featureId: string
+): Promise<Locator> {
+  return page.locator(`[data-testid="drag-handle-${featureId}"]`);
+}

apps/app/tests/utils/views/context.ts

@@ -0,0 +1,188 @@
+import { Page, Locator } from "@playwright/test";
+import { clickElement, fillInput } from "../core/interactions";
+import { waitForElement, waitForElementHidden } from "../core/waiting";
+import { getByTestId } from "../core/elements";
+import { expect } from "@playwright/test";
+
+/**
+ * Get the context file list element
+ */
+export async function getContextFileList(page: Page): Promise<Locator> {
+  return page.locator('[data-testid="context-file-list"]');
+}
+
+/**
+ * Click on a context file in the list
+ */
+export async function clickContextFile(
+  page: Page,
+  fileName: string
+): Promise<void> {
+  const fileButton = page.locator(`[data-testid="context-file-${fileName}"]`);
+  await fileButton.click();
+}
+
+/**
+ * Get the context editor element
+ */
+export async function getContextEditor(page: Page): Promise<Locator> {
+  return page.locator('[data-testid="context-editor"]');
+}
+
+/**
+ * Get the context editor content
+ */
+export async function getContextEditorContent(page: Page): Promise<string> {
+  const editor = await getByTestId(page, "context-editor");
+  return await editor.inputValue();
+}
+
+/**
+ * Set the context editor content
+ */
+export async function setContextEditorContent(
+  page: Page,
+  content: string
+): Promise<void> {
+  const editor = await getByTestId(page, "context-editor");
+  await editor.fill(content);
+}
+
+/**
+ * Open the add context file dialog
+ */
+export async function openAddContextFileDialog(page: Page): Promise<void> {
+  await clickElement(page, "add-context-file");
+  await waitForElement(page, "add-context-dialog");
+}
+
+/**
+ * Create a text context file via the UI
+ */
+export async function createContextFile(
+  page: Page,
+  filename: string,
+  content: string
+): Promise<void> {
+  await openAddContextFileDialog(page);
+  await clickElement(page, "add-text-type");
+  await fillInput(page, "new-file-name", filename);
+  await fillInput(page, "new-file-content", content);
+  await clickElement(page, "confirm-add-file");
+  await waitForElementHidden(page, "add-context-dialog");
+}
+
+/**
+ * Create an image context file via the UI
+ */
+export async function createContextImage(
+  page: Page,
+  filename: string,
+  imagePath: string
+): Promise<void> {
+  await openAddContextFileDialog(page);
+  await clickElement(page, "add-image-type");
+  await fillInput(page, "new-file-name", filename);
+  await page.setInputFiles('[data-testid="image-upload-input"]', imagePath);
+  await clickElement(page, "confirm-add-file");
+  await waitForElementHidden(page, "add-context-dialog");
+}
+
+/**
+ * Delete a context file via the UI (must be selected first)
+ */
+export async function deleteSelectedContextFile(page: Page): Promise<void> {
+  await clickElement(page, "delete-context-file");
+  await waitForElement(page, "delete-context-dialog");
+  await clickElement(page, "confirm-delete-file");
+  await waitForElementHidden(page, "delete-context-dialog");
+}
+
+/**
+ * Save the current context file
+ */
+export async function saveContextFile(page: Page): Promise<void> {
+  await clickElement(page, "save-context-file");
+  // Wait for save to complete (button shows "Saved")
+  await page.waitForFunction(
+    () =>
+      document
+        .querySelector('[data-testid="save-context-file"]')
+        ?.textContent?.includes("Saved"),
+    { timeout: 5000 }
+  );
+}
+
+/**
+ * Toggle markdown preview mode
+ */
+export async function toggleContextPreviewMode(page: Page): Promise<void> {
+  await clickElement(page, "toggle-preview-mode");
+}
+
+/**
+ * Wait for a specific file to appear in the context file list
+ */
+export async function waitForContextFile(
+  page: Page,
+  filename: string,
+  timeout: number = 10000
+): Promise<void> {
+  const locator = await getByTestId(page, `context-file-${filename}`);
+  await locator.waitFor({ state: "visible", timeout });
+}
+
+/**
+ * Click a file in the list and wait for it to be selected (toolbar visible)
+ * Uses JavaScript click to ensure React event handler fires
+ */
+export async function selectContextFile(
+  page: Page,
+  filename: string,
+  timeout: number = 10000
+): Promise<void> {
+  const fileButton = await getByTestId(page, `context-file-${filename}`);
+  await fileButton.waitFor({ state: "visible", timeout });
+
+  // Small delay to ensure React has finished rendering the file list
+  await page.waitForTimeout(200);
+
+  // Use JavaScript click to ensure React onClick handler fires
+  await fileButton.evaluate((el) => (el as HTMLButtonElement).click());
+
+  // Wait for the file to be selected (toolbar with delete button becomes visible)
+  const deleteButton = await getByTestId(page, "delete-context-file");
+  await expect(deleteButton).toBeVisible({
+    timeout,
+  });
+}
+
+/**
+ * Wait for file content panel to load (either editor, preview, or image)
+ */
+export async function waitForFileContentToLoad(page: Page): Promise<void> {
+  // Wait for either the editor, preview, or image to appear
+  await page.waitForSelector(
+    '[data-testid="context-editor"], [data-testid="markdown-preview"], [data-testid="image-preview"]',
+    { timeout: 10000 }
+  );
+}
+
+/**
+ * Switch from preview mode to edit mode for markdown files
+ * Markdown files open in preview mode by default, this helper switches to edit mode
+ */
+export async function switchToEditMode(page: Page): Promise<void> {
+  // First wait for content to load
+  await waitForFileContentToLoad(page);
+
+  const markdownPreview = await getByTestId(page, "markdown-preview");
+  const isPreview = await markdownPreview.isVisible().catch(() => false);
+
+  if (isPreview) {
+    await clickElement(page, "toggle-preview-mode");
+    await page.waitForSelector('[data-testid="context-editor"]', {
+      timeout: 5000,
+    });
+  }
+}

apps/app/tests/utils/views/settings.ts

@@ -0,0 +1,8 @@
+import { Page, Locator } from "@playwright/test";
+
+/**
+ * Get the settings view scrollable content area
+ */
+export async function getSettingsContentArea(page: Page): Promise<Locator> {
+  return page.locator('[data-testid="settings-view"] .overflow-y-auto');
+}

apps/app/tests/utils/views/setup.ts

@@ -0,0 +1,75 @@
+import { Page, Locator } from "@playwright/test";
+import { getByTestId } from "../core/elements";
+import { waitForElement } from "../core/waiting";
+import { setupFirstRun } from "../project/setup";
+
+/**
+ * Wait for setup view to be visible
+ */
+export async function waitForSetupView(page: Page): Promise<Locator> {
+  return waitForElement(page, "setup-view", { timeout: 10000 });
+}
+
+/**
+ * Click "Get Started" button on setup welcome step
+ */
+export async function clickSetupGetStarted(page: Page): Promise<void> {
+  const button = await getByTestId(page, "setup-start-button");
+  await button.click();
+}
+
+/**
+ * Click continue on Claude setup step
+ */
+export async function clickClaudeContinue(page: Page): Promise<void> {
+  const button = await getByTestId(page, "claude-next-button");
+  await button.click();
+}
+
+/**
+ * Click finish on setup complete step
+ */
+export async function clickSetupFinish(page: Page): Promise<void> {
+  const button = await getByTestId(page, "setup-finish-button");
+  await button.click();
+}
+
+/**
+ * Enter Anthropic API key in setup
+ */
+export async function enterAnthropicApiKey(
+  page: Page,
+  apiKey: string
+): Promise<void> {
+  // Click "Use Anthropic API Key Instead" button
+  const useApiKeyButton = await getByTestId(page, "use-api-key-button");
+  await useApiKeyButton.click();
+
+  // Enter the API key
+  const input = await getByTestId(page, "anthropic-api-key-input");
+  await input.fill(apiKey);
+
+  // Click save button
+  const saveButton = await getByTestId(page, "save-anthropic-key-button");
+  await saveButton.click();
+}
+
+/**
+ * Enter OpenAI API key in setup
+ */
+export async function enterOpenAIApiKey(
+  page: Page,
+  apiKey: string
+): Promise<void> {
+  // Click "Enter OpenAI API Key" button
+  const useApiKeyButton = await getByTestId(page, "use-openai-key-button");
+  await useApiKeyButton.click();
+
+  // Enter the API key
+  const input = await getByTestId(page, "openai-api-key-input");
+  await input.fill(apiKey);
+
+  // Click save button
+  const saveButton = await getByTestId(page, "save-openai-key-button");
+  await saveButton.click();
+}

apps/app/tests/utils/views/spec-editor.ts

@@ -0,0 +1,118 @@
+import { Page, Locator } from "@playwright/test";
+import { clickElement } from "../core/interactions";
+import { navigateToSpec } from "../navigation/views";
+
+/**
+ * Get the spec editor element
+ */
+export async function getSpecEditor(page: Page): Promise<Locator> {
+  return page.locator('[data-testid="spec-editor"]');
+}
+
+/**
+ * Get the spec editor content
+ */
+export async function getSpecEditorContent(page: Page): Promise<string> {
+  const editor = await getSpecEditor(page);
+  return await editor.inputValue();
+}
+
+/**
+ * Set the spec editor content
+ */
+export async function setSpecEditorContent(
+  page: Page,
+  content: string
+): Promise<void> {
+  const editor = await getSpecEditor(page);
+  await editor.fill(content);
+}
+
+/**
+ * Click the save spec button
+ */
+export async function clickSaveSpec(page: Page): Promise<void> {
+  await clickElement(page, "save-spec");
+}
+
+/**
+ * Click the reload spec button
+ */
+export async function clickReloadSpec(page: Page): Promise<void> {
+  await clickElement(page, "reload-spec");
+}
+
+/**
+ * Check if the spec view path display shows the correct .automaker path
+ */
+export async function getDisplayedSpecPath(page: Page): Promise<string | null> {
+  const specView = page.locator('[data-testid="spec-view"]');
+  const pathElement = specView.locator("p.text-muted-foreground").first();
+  return await pathElement.textContent();
+}
+
+/**
+ * Navigate to the spec editor view
+ */
+export async function navigateToSpecEditor(page: Page): Promise<void> {
+  await navigateToSpec(page);
+}
+
+/**
+ * Get the CodeMirror editor content
+ */
+export async function getEditorContent(page: Page): Promise<string> {
+  // CodeMirror uses a contenteditable div with class .cm-content
+  const content = await page
+    .locator('[data-testid="spec-editor"] .cm-content')
+    .textContent();
+  return content || "";
+}
+
+/**
+ * Set the CodeMirror editor content by selecting all and typing
+ */
+export async function setEditorContent(page: Page, content: string): Promise<void> {
+  // Click on the editor to focus it
+  const editor = page.locator('[data-testid="spec-editor"] .cm-content');
+  await editor.click();
+
+  // Wait for focus
+  await page.waitForTimeout(200);
+
+  // Select all content (Cmd+A on Mac, Ctrl+A on others)
+  const isMac = process.platform === "darwin";
+  await page.keyboard.press(isMac ? "Meta+a" : "Control+a");
+
+  // Wait for selection
+  await page.waitForTimeout(100);
+
+  // Delete the selected content first
+  await page.keyboard.press("Backspace");
+
+  // Wait for deletion
+  await page.waitForTimeout(100);
+
+  // Type the new content
+  await page.keyboard.type(content, { delay: 10 });
+
+  // Wait for typing to complete
+  await page.waitForTimeout(200);
+}
+
+/**
+ * Click the save button
+ */
+export async function clickSaveButton(page: Page): Promise<void> {
+  const saveButton = page.locator('[data-testid="save-spec"]');
+  await saveButton.click();
+
+  // Wait for the button text to change to "Saved" indicating save is complete
+  await page.waitForFunction(
+    () => {
+      const btn = document.querySelector('[data-testid="save-spec"]');
+      return btn?.textContent?.includes("Saved");
+    },
+    { timeout: 5000 }
+  );
+}