Skip to content

OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.

Python
44.1 KB
Raw Blame
import { expect, Locator, Page } from "@playwright/test";
import path from "path";
import logger from "../utils/logger";

function escapeRegExp(str: string): string {
  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
}

export class Knowledge {
  // Locators - defined at class level for better maintainability
  private readonly knowledgeLink = () =>
    this.page.getByRole("link", { name: "Knowledge" });
  private readonly projectKnowledgeHeading = () =>
    this.page.getByText("Project Knowledge");
  private readonly searchErrorGeneric = () =>
    this.page.getByText(/search error/i);
  private readonly transportError = () =>
    this.page.getByText(/TransportError.*search_phase_execution_exception/i);
  private readonly embeddingError = () =>
    this.page.getByText(/Failed to embed with model/i);
  private readonly fetchLatestDocsButton = () =>
    this.page.getByRole("button", { name: "Fetch latest docs" });
  private readonly openragDocsRefreshedToast = () =>
    this.page.getByText(/OpenRAG docs were refreshed/i).first();
  private readonly taskCompletedToast = () =>
    this.page.getByText(/task completed/i).first();
  readonly addKnowledgeButton = () =>
    this.page.getByRole("button", { name: /^Add [Kk]nowledge$/i });
  private readonly fileInput = () =>
    this.page.locator('input[type="file"]').first();
  private readonly overwriteButton = () =>
    this.page.getByRole("button", { name: "Overwrite" });
  private readonly fileOption = () =>
    this.page.getByText("File", { exact: true });
  private readonly folderOption = () => this.page.getByText("Folder");
  private readonly firstPageButton = () =>
    this.page.getByRole("button", { name: /first page/i });
  private readonly nextPageButton = () =>
    this.page.getByRole("button", { name: /next page/i });
  private readonly gridContainer = () => this.page.locator(".ag-body-viewport");
  private readonly searchInput = () =>
    this.page.locator('input[placeholder*="Search"]');
  private readonly deleteButton = () =>
    this.page.getByRole("button", { name: "Delete" });
  private readonly deleteDocumentDialog = () =>
    this.page.locator("text=Delete document");
  private readonly confirmDeleteButton = () =>
    this.page.getByRole("button", { name: "Delete" }).last();
  private readonly deleteSuccessToast = () =>
    this.page
      .getByText(
        /successfully deleted \d+ document|document.*deleted|deleted.*document/i,
      )
      .first();
  private readonly knowledgeFiltersHeading = () =>
    this.page.getByText("Knowledge Filters");
  private readonly createFilterButton = () =>
    this.page.locator('button[title="Create New Filter"]');
  private readonly filterNameInput = () =>
    this.page
      .locator("input#filter-name")
      .or(this.page.locator('input[placeholder*="Filter name"]'))
      .first();
  private readonly allSourcesButton = () =>
    this.page.locator("button").filter({ hasText: "All sources" }).first();
  private readonly allSourcesOption = () =>
    this.page
      .locator('[role="option"]')
      .filter({ hasText: "All sources" })
      .first();
  private readonly searchOptionsInput = () =>
    this.page
      .locator('input[placeholder*="Search options"]')
      .or(this.page.locator('input[placeholder*="search"]'))
      .first();
  private readonly createFilterSubmitButton = () =>
    this.page.getByRole("button", { name: /Create Filter/i });
  private readonly deleteFilterButton = () =>
    this.page.getByRole("button", { name: "Delete Filter" });
  private readonly chunkElements = () => this.page.locator("blockquote");
  private readonly grid = () =>
    this.page.locator(".ag-body-horizontal-scroll-viewport");

  /**
   * Get locator for data rows with checkboxes
   * @returns Locator for data rows
   */
  private getDataRows(): Locator {
    return this.page.locator('[role="row"]').filter({
      has: this.page.locator('input[type="checkbox"]'),
    });
  }

  /**
   * Get locator for a row by its row-id attribute
   * @param key - The row-id value
   * @returns Locator for the row
   */
  private getRowById(key: string): Locator {
    return this.page.locator(`[role="row"][row-id="${key}"]`);
  }

  /**
   * Get locator for source cell with exact text match
   * @param key - The text to match
   * @returns Locator for the cell
   */
  private getSourceCellByExactText(key: string): Locator {
    return this.page
      .locator('[col-id="source"]')
      .getByText(new RegExp(`^${escapeRegExp(key)}$`))
      .first();
  }

  /**
   * Get locator for source cell with title attribute
   * @param key - The title value
   * @returns Locator for the cell
   */
  private getSourceCellByTitle(key: string): Locator {
    return this.page.locator(`[col-id="source"] [title="${key}"]`).first();
  }

  /**
   * Get locator for source cell with partial text match
   * @param key - The text to match
   * @returns Locator for the cell
   */
  private getSourceCellByPartialText(key: string): Locator {
    return this.page
      .locator('[col-id="source"]')
      .getByText(key, { exact: false })
      .first();
  }

  /**
   * Get locator for files uploaded successfully message
   * @param count - Number of files
   * @returns Locator for the message
   */
  private getFilesUploadedMessage(count: number): Locator {
    return this.page.getByText(`${count} files uploaded successfully`);
  }

  /**
   * Get locator for source option in filter dropdown
   * @param sourceFileName - Name of the source file
   * @returns Locator for the option
   */
  private getSourceOption(sourceFileName: string): Locator {
    return this.page
      .locator('[role="option"]')
      .filter({ hasText: sourceFileName })
      .first();
  }

  /**
   * Get locator for filter item by name
   * @param filterName - Name of the filter
   * @returns Locator for the filter item
   */
  private getFilterItem(filterName: string): Locator {
    return this.page.locator(`text="${filterName}"`).first();
  }

  /**
   * Get locator for status column in a row
   * @param row - The row locator
   * @returns Locator for the status cell
   */
  private getStatusCell(row: Locator): Locator {
    return row.locator('[col-id="status"]');
  }

  /**
   * Get locator for checkbox in a row
   * @param row - The row locator
   * @returns Locator for the checkbox
   */
  private getRowCheckbox(row: Locator): Locator {
    return row.locator('input[type="checkbox"]');
  }

  constructor(private page: Page) {}

  /**
   * Check if there's a critical search error in the knowledge base
   * Detects two types of errors:
   * 1. OpenSearch database errors (search_phase_execution_exception)
   * 2. Model-specific embedding errors (Failed to embed with model)
   * @throws Error if search error is detected
   */
  private async checkForSearchError() {
    // Wait a moment for any error messages to appear
    await this.page.waitForTimeout(1000);

    // Look for different types of search error messages
    const searchError = this.searchErrorGeneric();
    const transport = this.transportError();
    const embedding = this.embeddingError();

    try {
      // Check if any error message is visible
      const errorCheck = await Promise.race([
        searchError.isVisible().then(async (visible) => {
          if (visible) {
            // Get the full error text to determine the type
            const errorText = await searchError.textContent();
            return { type: "search_error", text: errorText };
          }
          return null;
        }),
        transport.isVisible().then((visible) =>
          visible
            ? {
                type: "transport_error",
                text: "TransportError(503, search_phase_execution_exception)",
              }
            : null,
        ),
        embedding.isVisible().then(async (visible) => {
          if (visible) {
            const errorText = await embedding.textContent();
            return { type: "embedding_error", text: errorText };
          }
          return null;
        }),
        new Promise<null>((resolve) => setTimeout(() => resolve(null), 2000)),
      ]);

      if (errorCheck) {
        // Determine error type and throw appropriate error
        if (
          errorCheck.type === "embedding_error" ||
          errorCheck.text?.includes("Failed to embed")
        ) {
          // Extract model name from error message if possible
          const modelMatch = errorCheck.text?.match(/model\s+([^\s]+)/i);
          const modelName = modelMatch ? modelMatch[1] : "unknown";

          throw new Error(
            `❌ MODEL ERROR: Search failed due to embedding model issue.\n` +
              `   Model: ${modelName}\n` +
              `   Error: ${errorCheck.text}\n` +
              `   This occurs when searching with a model that has documents indexed with it but the model is unavailable or misconfigured.\n` +
              `   Solution: Either fix the model configuration or switch to a different embedding model.`,
          );
        } else {
          // OpenSearch database error
          throw new Error(
            "❌ CRITICAL: Knowledge base search error detected (OpenSearch database issue).\n" +
              "   This error prevents all knowledge base operations.\n" +
              `   Error: ${errorCheck.text}\n` +
              "   Solution: Check OpenSearch service status and configuration.",
          );
        }
      }
    } catch (error) {
      // If it's our custom error, re-throw it
      if (
        error instanceof Error &&
        (error.message.includes("CRITICAL") ||
          error.message.includes("MODEL ERROR"))
      ) {
        throw error;
      }
      // Otherwise, no error found (which is good)
    }
  }

  /**
   * Check if the page is still open and usable
   */
  private isPageClosed(): boolean {
    return this.page.isClosed();
  }

  /**
   * Safe wrapper for waitForTimeout that skips if the page is closed.
   * Prevents "Target page, context or browser has been closed" errors
   * in cleanup/catch blocks after the test has timed out.
   */
  private async safeWait(ms: number): Promise<void> {
    if (this.isPageClosed()) return;
    try {
      await this.page.waitForTimeout(ms);
    } catch {
      // Page was closed during the wait — swallow silently
    }
  }

  async open() {
    // If already on the knowledge page, nothing to do
    if (this.page.url().endsWith("/knowledge")) {
      await expect(this.projectKnowledgeHeading()).toBeVisible({
        timeout: 15000,
      });
      await this.checkForSearchError();
      return;
    }
    // Wait for any in-progress navigation to settle before clicking
    await this.page
      .waitForLoadState("domcontentloaded", { timeout: 15000 })
      .catch(() => {});
    const link = this.knowledgeLink();
    await expect(link).toBeVisible({ timeout: 15000 });
    await link.click({ timeout: 30000 });
    await expect(this.projectKnowledgeHeading()).toBeVisible({
      timeout: 30000,
    });
    // Automatically check for critical errors every time we open knowledge base
    await this.checkForSearchError();
  }

  /**
   * Click "Fetch latest docs" button to refresh the document list.
   * Waits for the "What is OpenRAG?" document re-ingestion to complete.
   */
  async fetchLatestDocs() {
    if (this.isPageClosed()) return;
    const fetchButton = this.fetchLatestDocsButton();
    await fetchButton.click();
    // Wait for the refresh confirmation toast
    await expect(this.openragDocsRefreshedToast()).toBeVisible({
      timeout: 10000,
    });
    // Brief pause — reduced from 1000 ms to avoid eating into the test budget
    await this.safeWait(500);
    // "Fetch latest docs" triggers re-ingestion of "What is OpenRAG?" document.
    // Wait for its "Task completed" message so we don't confuse it with our own uploads.
    try {
      if (this.isPageClosed()) return;
      await expect(this.taskCompletedToast()).toBeVisible({ timeout: 30000 });
      logger.info(
        `  ⏳ Waiting for "What is OpenRAG?" re-ingestion to complete...`,
      );
      // Wait for the toast to auto-dismiss (~3-5 s); reduced from 6000 ms
      await this.safeWait(4000);
    } catch {
      // No task-completed message appeared — that's fine, just continue
      await this.safeWait(300);
    }
  }

  async ingestFile(
    filePath: string,
    overrideIfExists: boolean = true,
  ): Promise<string> {
    await this.open();
    // Handle both SaaS (lowercase) and OSS (uppercase) versions - use first() to handle multiple matches
    await this.addKnowledgeButton().click();
    const fileName = path.basename(filePath);
    // SaaS shows a dropdown (File / Folder / Google Drive / SharePoint) after clicking Add knowledge.
    // Click "File" if it appears; OSS exposes the file input directly without a dropdown.
    const fileOpt = this.fileOption();
    if (await fileOpt.isVisible().catch(() => false)) {
      await fileOpt.click();
    }
    await this.fileInput().setInputFiles(filePath);

    // Always check for the overwrite dialog — it appears whenever the file already exists
    try {
      const overwriteBtn = this.overwriteButton();
      await overwriteBtn.waitFor({ state: "visible", timeout: 4000 });
      if (overrideIfExists) {
        await expect(overwriteBtn).toBeEnabled({ timeout: 3000 });
        await overwriteBtn.click();
        logger.info(
          `Overwrite dialog detected — overwriting existing file: ${fileName}`,
        );
      } else {
        // Cancel the overwrite: click the Cancel button to dismiss the dialog
        await this.page.getByRole("button", { name: "Cancel" }).click();
        logger.info(
          `Overwrite dialog detected — cancelled (overrideIfExists=false): ${fileName}`,
        );
        return fileName;
      }
    } catch {
      // No overwrite dialog appeared — file is new, continue normally
    }

    // Wait for ingestion task to complete.
    // "task completed" toast may appear and auto-dismiss quickly, or may not appear
    // at all when overwriting an already-indexed file (the app skips re-queuing).
    // Give it a generous window but don't fail if it never shows — the file status
    // check in verifyDocumentActive is the authoritative confirmation.
    const taskCompleted = this.page.getByText(/task completed/i).first();
    await taskCompleted
      .waitFor({ state: "visible", timeout: 180000 })
      .catch(() => {
        logger.info(
          `  ℹ️  "task completed" toast not detected — file may have been processed immediately or toast was dismissed`,
        );
      });

    // Close the "Add Knowledge" dropdown menu by pressing Escape or clicking outside
    await this.page.keyboard.press("Escape");
    await this.page.waitForTimeout(500);
    return fileName;
  }

  async ingestFolder(
    folderPath: string,
    expectedFileCount: number,
    timeout: number = 180000,
  ): Promise<string> {
    await this.open();
    // Handle both SaaS (lowercase) and OSS (uppercase) versions - use first() to handle multiple matches
    await this.addKnowledgeButton().click();
    const folderName = path.basename(folderPath);
    const [fileChooser] = await Promise.all([
      this.page.waitForEvent("filechooser"),
      this.folderOption().click(),
    ]);
    await fileChooser.setFiles(folderPath);
    // ❗ DO NOT click Upload blindly
    await expect(this.getFilesUploadedMessage(expectedFileCount)).toBeVisible({
      timeout,
    });
    await this.page.keyboard.press("Escape");
    return folderName;
  }

  /**
   * Reset pagination to first page
   */
  private async resetToFirstPage() {
    const firstPageBtn = this.firstPageButton();
    try {
      const ariaDisabled = await firstPageBtn.getAttribute("aria-disabled");
      const classAttr = await firstPageBtn.getAttribute("class");
      const isDisabled =
        ariaDisabled === "true" || classAttr?.includes("ag-disabled");
      if (!isDisabled) {
        await firstPageBtn.click();
        await this.page.waitForTimeout(500);
      }
    } catch {
      // Button might not exist or not be clickable, that's fine
    }
  }

  /**
   * Find a row across all pages in the AG Grid.
   * Handles both virtualization scrolling and pagination.
   *
   * Strategy (in priority order):
   *   1. row-id attribute  — AG Grid sets this to the row's primary key; most reliable.
   *   2. Exact text match  — works when the cell text is not truncated.
   *   3. title attribute   — AG Grid often sets title="<full value>" even when the cell
   *                          text is visually truncated by CSS overflow.
   *   4. Partial text      — last resort; avoids false negatives from display trimming.
   *
   * @param key - The text to search for in the row
   * @returns The row locator if found
   * @throws Error if row not found after checking all pages
   */
  async findRowAcrossPages(key: string): Promise<Locator> {
    // Use the search box to filter the grid to the target document.
    // This avoids slow scroll/pagination loops and works even with large document lists.
    const searchInp = this.searchInput();
    if (await searchInp.isVisible()) {
      await searchInp.clear();
      await searchInp.fill(key);
      // Wait for the row-id attribute AG Grid sets to the data key.
      // More reliable than getByText: row-id is a flat attribute on the row element,
      // unaffected by AG Grid's deeply nested virtual DOM cell rendering.
      const rowById = this.getRowById(key);
      const exists = await rowById
        .first()
        .waitFor({ state: "visible", timeout: 10000 })
        .then(() => true)
        .catch(() => false);
      if (!exists) {
        // Not found — clear search and throw immediately
        await searchInp.clear();
        await this.page.waitForTimeout(300);
        throw new Error(`Row with key "${key}" not found across all pages`);
      }
      // Found via search — get the row while the filter is active
      const rowByTitle = this.getSourceCellByTitle(key);
      const rowByExact = this.getSourceCellByExactText(key);
      const rowByPartial = this.getSourceCellByPartialText(key);
      let foundRow: Locator | null = null;
      for (const candidate of [
        rowById.first(),
        rowByTitle,
        rowByExact,
        rowByPartial,
      ]) {
        if (await candidate.isVisible().catch(() => false)) {
          foundRow = candidate.locator(
            'xpath=ancestor-or-self::*[@role="row"][1]',
          );
          // For rowById, it already IS the row
          if (candidate === rowById.first()) foundRow = rowById.first();
          break;
        }
      }
      // Clear search to restore full grid view
      await searchInp.clear();
      await this.page.waitForTimeout(300);
      if (foundRow) return foundRow;
      throw new Error(`Row with key "${key}" not found across all pages`);
    }
    // Fallback: no search box — use original scroll/pagination approach
    // Always reset to first page at the start for consistent behavior
    await this.resetToFirstPage();
    const gridCont = this.gridContainer();
    // Helper: try all four strategies against the currently rendered DOM.
    const tryFind = async (timeout: number): Promise<Locator | null> => {
      // 1. row-id attribute (most reliable — set by AG Grid to the data key)
      const rowById = this.getRowById(key);
      try {
        await expect(rowById.first()).toBeVisible({ timeout });
        return rowById.first();
      } catch {
        // not found by row-id
      }
      // 2. Exact text match inside the source cell
      const exactSourceCell = this.getSourceCellByExactText(key);
      try {
        await expect(exactSourceCell).toBeVisible({ timeout });
        return exactSourceCell.locator('xpath=ancestor::*[@role="row"][1]');
      } catch {
        // not found by exact text
      }
      // 3. title attribute — handles truncated cell display text
      const cellWithTitle = this.getSourceCellByTitle(key);
      try {
        await expect(cellWithTitle).toBeVisible({ timeout });
        return cellWithTitle.locator('xpath=ancestor::*[@role="row"][1]');
      } catch {
        // not found by title
      }
      // 4. Partial / contains match as last resort
      const looseCell = this.getSourceCellByPartialText(key);
      try {
        await expect(looseCell).toBeVisible({ timeout });
        return looseCell.locator('xpath=ancestor::*[@role="row"][1]');
      } catch {
        return null;
      }
    };
    let pagesChecked = 0;
    const MAX_PAGES = 50;
    while (pagesChecked < MAX_PAGES) {
      // Check the current viewport first
      const found = await tryFind(3000);
      if (found) return found;
      // Scroll down incrementally inside AG Grid to reveal virtualised rows
      const prevScrollTop: number = await gridCont.evaluate(
        (el) => el.scrollTop,
      );
      await gridCont.evaluate((el) => {
        el.scrollTop += el.clientHeight;
      });
      await this.page.waitForTimeout(400);
      const newScrollTop: number = await gridCont.evaluate(
        (el) => el.scrollTop,
      );
      const foundAfterScroll = await tryFind(2000);
      if (foundAfterScroll) return foundAfterScroll;
      // If scroll position didn't change we've hit the bottom of this page
      if (newScrollTop === prevScrollTop) {
        // Reset scroll before moving to the next paginated page
        await gridCont.evaluate((el) => {
          el.scrollTop = 0;
        });
        const nextButton = this.nextPageButton();
        // Check disabled via aria-disabled, class, or whether the button is actually enabled
        const ariaDisabled = await nextButton.getAttribute("aria-disabled");
        const classAttr = await nextButton.getAttribute("class");
        const isDisabled =
          ariaDisabled === "true" ||
          classAttr?.includes("ag-disabled") ||
          !(await nextButton.isEnabled());
        if (isDisabled) break;
        await nextButton.click();
        pagesChecked++;
        await this.page.waitForTimeout(500);
      }
    }
    throw new Error(`Row with key "${key}" not found across all pages`);
  }

  /**
   * Delete a document by name.
   * Uses findRowAcrossPages for reliable document location.
   * @param documentName - The name of the document to delete
   * @returns true if deletion was successful, false if document not found
   */
  async deleteDocument(
    documentNames: string | string[],
  ): Promise<boolean | { found: string[]; notFound: string[] }> {
    await this.open();
    // Handle single document case
    if (typeof documentNames === "string") {
      let row: Locator;
      try {
        row = await this.findRowAcrossPages(documentNames);
      } catch {
        return false; // Document not found
      }
      // Select the document (click checkbox)
      const checkbox = this.getRowCheckbox(row);
      await checkbox.click();
      // Click the Delete button
      const deleteBtn = this.deleteButton();
      await expect(deleteBtn).toBeVisible();
      await deleteBtn.click();
      // Confirm deletion in the dialog
      const confirmDialog = this.deleteDocumentDialog();
      await expect(confirmDialog).toBeVisible({ timeout: 5000 });
      const confirmButton = this.confirmDeleteButton();
      await confirmButton.click();
      // Wait for success message
      await expect(this.deleteSuccessToast()).toBeVisible({ timeout: 10000 });
      // Wait for the success message to disappear
      await this.page.waitForTimeout(1000);
      return true;
    }
    // Handle multiple documents case
    const found: string[] = [];
    const notFound: string[] = [];
    // Find and select all documents that exist
    // findRowAcrossPages now resets to first page at the start automatically
    for (const documentName of documentNames) {
      try {
        const row = await this.findRowAcrossPages(documentName);
        const checkbox = this.getRowCheckbox(row);
        await checkbox.click();
        found.push(documentName);
        await this.page.waitForTimeout(200); // Small delay between selections
      } catch {
        notFound.push(documentName);
      }
    }
    // If no documents were found, return early
    if (found.length === 0) {
      return { found, notFound };
    }
    // Click the Delete button
    const deleteBtn = this.deleteButton();
    await expect(deleteBtn).toBeVisible();
    await deleteBtn.click();
    // Confirm deletion in the dialog
    const confirmDialog = this.deleteDocumentDialog();
    await expect(confirmDialog).toBeVisible({ timeout: 5000 });
    const confirmButton = this.confirmDeleteButton();
    await confirmButton.click();
    // Wait for success message
    await expect(this.deleteSuccessToast()).toBeVisible({ timeout: 10000 });
    // Wait for the success message to disappear
    await this.page.waitForTimeout(1000);
    return { found, notFound };
  }

  /**
   * Open a document by clicking on it.
   * Uses findRowAcrossPages for reliable document location.
   * @param fileName - The name of the document to open
   */
  async openDocument(fileName: string) {
    await this.open();

    // Find the document row using reliable method
    const row = await this.findRowAcrossPages(fileName);

    // Click on the document link button
    const fileButton = row
      .getByRole("button", { name: fileName })
      .or(row.locator("button").filter({ hasText: fileName }));

    await expect(fileButton).toBeVisible({ timeout: 10000 });
    await expect(fileButton).not.toHaveClass(/cursor-default/, {
      timeout: 10000,
    });
    await fileButton.click();
    await this.page.waitForURL(/\/knowledge\/chunks/, { timeout: 15000 });
  }

  async getFirstChunkText(): Promise<string> {
    await expect(this.page.getByText(/Chunk \d+/i).first()).toBeVisible({
      timeout: 15000,
    });

    const chunk = this.page.locator("blockquote").first();
    return (await chunk.textContent()) || "";
  }

  async logFirstChunk(docName: string): Promise<string> {
    await this.openDocument(docName);
    const firstChunk = await this.getFirstChunkText();
    logger.info(`First chunk for "${docName}": ${firstChunk}`);
    return firstChunk;
  }

  /**
   * Verify that a document has 'Active' status.
   * Uses findRowAcrossPages for reliable document location.
   * @param docName - The name of the document to verify
   */
  async verifyDocumentActive(docName: string) {
    await this.open();
    // Use search to filter to the document, then poll its status directly.
    // Keeping the search active while checking status avoids stale-locator issues
    // caused by grid re-renders when search is cleared.
    const searchInp = this.searchInput();

    // Wait for the search input to be visible before entering the polling loop.
    // Without this guard the loop body executes against a not-yet-rendered grid,
    // which causes fill() to silently no-op and row lookups to always return null,
    // burning the entire 2-minute deadline with no progress.
    const searchReady = await searchInp
      .waitFor({ state: "visible", timeout: 15000 })
      .then(() => true)
      .catch(() => false);
    if (!searchReady) {
      throw new Error(
        `Knowledge grid search input not visible — page may not have loaded correctly`,
      );
    }

    const deadline = Date.now() + 300000; // 5 minutes for indexing to complete
    while (Date.now() < deadline) {
      // Filter grid to the target document
      await searchInp.clear();
      await searchInp.fill(docName);
      await this.page.waitForTimeout(800);
      // Try row-id first, fall back to partial source-cell text match
      let row = this.getRowById(docName).first();
      if (!(await row.isVisible().catch(() => false))) {
        const partial = this.getSourceCellByPartialText(docName);
        if (await partial.isVisible().catch(() => false)) {
          row = partial.locator('xpath=ancestor::*[@role="row"][1]');
        }
      }
      const rowVisible = await row.isVisible().catch(() => false);
      if (!rowVisible) {
        logger.info(`  ⏳ Document "${docName}" not yet visible, retrying...`);
        // Refresh the grid before the next poll so newly ingested docs appear
        await searchInp.clear();
        continue;
      }
      // Row is visible — scroll right to reveal the Status column and read it
      await this.grid().evaluate((el) => {
        el.scrollLeft = el.scrollWidth;
      });
      await this.page.waitForTimeout(300);
      const status = this.getStatusCell(row);
      let statusText = (await status.innerText().catch(() => "")) || "";
      if (!statusText) {
        statusText = (await status.textContent().catch(() => "")) || "";
      }
      if (statusText.includes("Animated Processing Icon")) {
        statusText = "Processing";
      }
      if (statusText.toLowerCase().includes("active")) {
        // Clear search before returning
        await searchInp.clear();
        return;
      }
      // Terminal statuses will never transition to Active — fail immediately
      // instead of burning the full 5-minute deadline before throwing.
      const normalised = statusText.trim().toLowerCase();
      if (
        normalised === "failed" ||
        normalised === "cancelled" ||
        normalised === "duplicate"
      ) {
        await searchInp.clear();
        throw new Error(
          `Document "${docName}" reached terminal status "${statusText.trim()}" and will never become Active`,
        );
      }
      logger.info(
        `  ⏳ Document "${docName}" status: "${statusText.trim()}", waiting...`,
      );
      await this.page.waitForTimeout(5000);
    }
    await searchInp.clear();
    throw new Error(
      `Document "${docName}" did not reach Active status within the timeout`,
    );
  }

  /**
   * Verify that a document has been fully processed — either indexed as Active
   * or recognised as a content duplicate (Duplicate). Both outcomes mean the
   * system handled the file without error; use this instead of
   * verifyDocumentActive when duplicate detection is expected to fire.
   */
  async verifyDocumentProcessed(docName: string) {
    await this.open();
    const searchInp = this.searchInput();
    const searchReady = await searchInp
      .waitFor({ state: "visible", timeout: 15000 })
      .then(() => true)
      .catch(() => false);
    if (!searchReady) {
      throw new Error(
        `Knowledge grid search input not visible — page may not have loaded correctly`,
      );
    }

    const deadline = Date.now() + 300000;
    while (Date.now() < deadline) {
      await searchInp.clear();
      await searchInp.fill(docName);
      await this.page.waitForTimeout(800);
      let row = this.getRowById(docName).first();
      if (!(await row.isVisible().catch(() => false))) {
        const partial = this.getSourceCellByPartialText(docName);
        if (await partial.isVisible().catch(() => false)) {
          row = partial.locator('xpath=ancestor::*[@role="row"][1]');
        }
      }
      if (!(await row.isVisible().catch(() => false))) {
        logger.info(`  ⏳ Document "${docName}" not yet visible, retrying...`);
        await searchInp.clear();
        continue;
      }
      await this.grid().evaluate((el) => {
        el.scrollLeft = el.scrollWidth;
      });
      await this.page.waitForTimeout(300);
      const status = this.getStatusCell(row);
      let statusText = (await status.innerText().catch(() => "")) || "";
      if (!statusText) {
        statusText = (await status.textContent().catch(() => "")) || "";
      }
      if (statusText.includes("Animated Processing Icon")) {
        statusText = "Processing";
      }
      const normalised = statusText.trim().toLowerCase();
      // Both Active and Duplicate are successful terminal outcomes.
      if (normalised.includes("active") || normalised === "duplicate") {
        await searchInp.clear();
        logger.info(
          `  ✅ Document "${docName}" processed with status "${statusText.trim()}"`,
        );
        return;
      }
      // Hard-failure terminals — throw immediately.
      if (normalised === "failed" || normalised === "cancelled") {
        await searchInp.clear();
        throw new Error(
          `Document "${docName}" reached terminal status "${statusText.trim()}"`,
        );
      }
      logger.info(
        `  ⏳ Document "${docName}" status: "${statusText.trim()}", waiting...`,
      );
      await this.page.waitForTimeout(5000);
    }
    await searchInp.clear();
    throw new Error(
      `Document "${docName}" did not reach a processed status within the timeout`,
    );
  }

  /**
   * Verify that a document has been removed from the knowledge grid.
   * Searches for the document, and asserts it is NOT visible.
   * Passes immediately when the document is absent; fails if it is still present.
   * @param docName - The name of the document that should no longer exist
   */
  async verifyDocumentDeleted(docName: string): Promise<void> {
    await this.open();
    const searchInp = this.searchInput();
    await searchInp.clear();
    await searchInp.fill(docName);
    await this.page.waitForTimeout(800);
    const row = this.getRowById(docName).first();
    const isPresent = await row.isVisible({ timeout: 5000 }).catch(() => false);
    await searchInp.clear();
    if (isPresent) {
      throw new Error(`Document "${docName}" still exists after deletion`);
    }
    logger.info(`Document "${docName}" successfully deleted`);
  }

  async getDocumentStatus(docName: string): Promise<string> {
    await this.open();
    const row = await this.findRowAcrossPages(docName);
    const status = this.getStatusCell(row).first();
    await expect(status).toBeVisible({ timeout: 30000 });
    let statusText = (await status.innerText().catch(() => "")) || "";
    if (!statusText) {
      statusText = (await status.textContent().catch(() => "")) || "";
    }
    if (statusText.includes("Animated Processing Icon")) {
      statusText = "Processing";
    }
    return statusText.trim();
  }

  /**
   * Clear the search and return to unfiltered document list
   */
  async clearSearch() {
    // Find and click the close button (X) in the search bar
    const closeButton = this.searchInput()
      .locator("..")
      .locator("button")
      .first();
    try {
      await closeButton.click({ timeout: 2000 });
      await this.page.waitForTimeout(1000);
    } catch {
      // If close button not found or not clickable, clear the input manually
      const searchInp = this.searchInput();
      await searchInp.clear();
      await this.page.keyboard.press("Enter");
      await this.page.waitForTimeout(1000);
    }
  }

  /**
   * Search for content and get all matching document names
   * Extracts document names from the row-id attribute
   * @param searchTerm - The term to search for
   * @returns Array of document names that match the search
   */
  async getSearchResults(searchTerm: string): Promise<string[]> {
    await this.open();
    const searchInp = this.searchInput();
    await searchInp.fill(searchTerm);
    await this.page.keyboard.press("Enter");
    // Wait longer for search to complete and results to render
    // Increased from 2000ms to 5000ms to handle slower indexing/search operations
    await this.page.waitForTimeout(5000);
    // Check for search errors that may have occurred during the search operation
    // This is critical as search_phase_execution_exception can happen at any time
    await this.checkForSearchError();
    // Get all data rows with checkboxes (these are the actual document rows, not headers)
    const dataRows = this.getDataRows();
    const count = await dataRows.count();
    const documentNames: string[] = [];
    for (let i = 0; i < count; i++) {
      const row = dataRows.nth(i);
      // Get the row-id attribute which contains the document name
      const rowId = await row.getAttribute("row-id");
      // Filter out empty strings and add to results
      if (rowId && rowId.trim()) {
        documentNames.push(rowId.trim());
      }
    }
    // Clear the search to return to unfiltered state for next operations
    await this.clearSearch();
    return documentNames;
  }

  /**
   * Create a knowledge filter.
   * @param filterName - Name of the filter to create
   * @param sourceFileName - Name of the source file to include in the filter
   */
  async createKnowledgeFilter(filterName: string, sourceFileName: string) {
    // Just navigate to knowledge page directly
    await this.knowledgeLink().click();
    await expect(this.projectKnowledgeHeading()).toBeVisible();
    // Wait for the Knowledge Filters section to be visible
    await expect(this.knowledgeFiltersHeading()).toBeVisible({ timeout: 5000 });
    // Click the + button next to "Knowledge Filters" using the title attribute
    const createFilterBtn = this.createFilterButton();
    await expect(createFilterBtn).toBeVisible({ timeout: 5000 });
    await createFilterBtn.click();
    // Wait for the filter form to appear by checking for the filter name input
    const filterNameInp = this.filterNameInput();
    await expect(filterNameInp).toBeVisible({ timeout: 5000 });
    // Fill in the filter name
    await filterNameInp.fill(filterName);
    await this.page.waitForTimeout(300);
    // Click on the "All sources" button/dropdown in the filter form (right panel)
    const sourcesBtn = this.allSourcesButton();
    await expect(sourcesBtn).toBeVisible({ timeout: 5000 });
    await sourcesBtn.click();
    // Wait for the dropdown menu to appear
    await this.page.waitForTimeout(500);
    // First, deselect "All sources" by clicking on it
    const allSourcesOpt = this.allSourcesOption();
    await expect(allSourcesOpt).toBeVisible({ timeout: 3000 });
    await allSourcesOpt.click();
    await this.page.waitForTimeout(300);
    // Use the search input in the dropdown to find the specific document
    const searchInp = this.searchOptionsInput();
    await expect(searchInp).toBeVisible({ timeout: 3000 });
    await searchInp.fill(sourceFileName);
    // Wait longer for search results to appear (increased from 500ms to 2000ms)
    await this.page.waitForTimeout(2000);
    // Click on the filtered document option with retry logic
    const sourceOption = this.getSourceOption(sourceFileName);
    // Retry mechanism: wait up to 15 seconds for the document to appear in the dropdown
    let retries = 3;
    let found = false;
    while (retries > 0 && !found) {
      try {
        await expect(sourceOption).toBeVisible({ timeout: 5000 });
        found = true;
      } catch {
        retries--;
        if (retries > 0) {
          // Clear and re-enter the search to refresh the dropdown
          await searchInp.clear();
          await this.page.waitForTimeout(500);
          await searchInp.fill(sourceFileName);
          await this.page.waitForTimeout(2000);
        }
      }
    }
    // Final check - if still not found, throw error
    await expect(sourceOption).toBeVisible({ timeout: 5000 });
    await sourceOption.click();
    await this.page.waitForTimeout(500);
    // Close the dropdown by pressing Escape
    await this.page.keyboard.press("Escape");
    await this.page.waitForTimeout(300);
    // Click the "Create Filter" button
    const createButton = this.createFilterSubmitButton();
    await expect(createButton).toBeVisible({ timeout: 5000 });
    await createButton.click();
    // Wait for the filter to be created (form should close)
    await this.page.waitForTimeout(1000);
  }

  /**
   * Delete a knowledge filter by name.
   * @param filterName - Name of the filter to delete
   */
  async deleteKnowledgeFilter(filterName: string) {
    await this.knowledgeLink().click();
    await expect(this.projectKnowledgeHeading()).toBeVisible();
    // Find the filter in the sidebar and click on it to open the form
    const filterItem = this.getFilterItem(filterName);
    try {
      await expect(filterItem).toBeVisible({ timeout: 5000 });
      // Click on the filter to open the edit form
      await filterItem.click();
      // Wait for the "Delete Filter" button to appear (confirms form is open)
      const deleteBtn = this.deleteFilterButton();
      await expect(deleteBtn).toBeVisible({ timeout: 5000 });
      await deleteBtn.click();
      // Wait for the form to close (filter deleted)
      await this.page.waitForTimeout(1000);
    } catch {
      // Filter not found or already deleted
    }
  }

  /**
   * Get all visible chunks in the chunk viewer.
   * @returns Array of chunk texts in order (top to bottom)
   */
  private async getAllChunks(): Promise<string[]> {
    // Get all visible chunk elements (blockquotes contain chunk text)
    const chunks = this.chunkElements();
    await expect(chunks.first()).toBeVisible({ timeout: 5000 });
    const count = await chunks.count();
    const chunkTexts: string[] = [];
    for (let i = 0; i < count; i++) {
      const chunkText = await chunks.nth(i).textContent();
      if (chunkText && chunkText.trim()) {
        chunkTexts.push(chunkText.trim());
      }
    }
    return chunkTexts;
  }

  /**
   * Search for chunks containing a specific token and return top 2 results.
   * @param searchToken - The token to search for in chunks
   * @returns Array containing the top 2 chunk texts after search
   */
  async searchChunks(searchToken: string): Promise<string[]> {
    // Locate the chunk-specific search input (not the knowledge-list search bar).
    // Both inputs match placeholder*="Search"; narrow to "chunks" to avoid ambiguity.
    const searchInp = this.page.locator('input[placeholder*="chunks"]');
    await expect(searchInp).toBeVisible({ timeout: 5000 });
    // Clear any existing search and enter the token
    await searchInp.clear();
    await searchInp.fill(searchToken);
    await this.page.keyboard.press("Enter");
    // The panel filters via React's useDeferredValue, so the DOM update is
    // asynchronous. Poll until at least one rendered blockquote contains the
    // search token — this is the only reliable signal that the deferred filter
    // update has fully committed, rather than treating a visible-but-stale
    // first chunk or a fixed delay as evidence of completion.
    await expect
      .poll(
        async () => {
          const chunks = this.chunkElements();
          const count = await chunks.count();
          for (let i = 0; i < count; i++) {
            const text = await chunks.nth(i).textContent();
            if (text?.includes(searchToken)) return true;
          }
          return false;
        },
        { timeout: 15000 },
      )
      .toBe(true);
    // Get all chunks after search
    const allChunks = await this.getAllChunks();
    // Return only the top 2 chunks
    return allChunks.slice(0, 2);
  }

  // ============================================================================
  // METHODS ADDED FOR AUTOMATED TESTING SUITE
  // ============================================================================

  /**
   * Delete all documents by selecting the master checkbox
   */
  async deleteAllDocuments() {
    // Check if the knowledge base is already empty
    const noKnowledgeMsg = this.page.getByText("No knowledge", { exact: true });
    const isEmpty = await noKnowledgeMsg
      .isVisible({ timeout: 2000 })
      .catch(() => false);

    if (!isEmpty) {
      // If there are files, select the source checkbox to select all files
      const selectAllCheckbox = this.page
        .locator('.ag-header-row input[type="checkbox"]')
        .first();

      if (await selectAllCheckbox.isVisible({ timeout: 2000 })) {
        await selectAllCheckbox.click();
        await this.page.waitForTimeout(1000);

        const deleteBtn = this.page.getByRole("button", { name: "Delete" });
        if (await deleteBtn.isEnabled()) {
          await deleteBtn.click();
          await this.page.waitForTimeout(1000);

          // Confirm deletion
          const confirmBtn = this.page
            .getByRole("button", { name: "Delete" })
            .last();
          await confirmBtn.click();

          // Wait for the 'No knowledge' empty state to appear
          await expect(noKnowledgeMsg).toBeVisible({ timeout: 10000 });
        }
      }
    }
  }

  /**
   * Start a file upload process without waiting for it to complete.
   * Useful for negative test cases like testing upload cancellation.
   */
  async ingestFileNonBlocking(filePath: string) {
    await this.open();
    await this.addKnowledgeButton().click();
    await this.fileInput().setInputFiles(filePath);

    try {
      const overwriteBtn = this.overwriteButton();
      await overwriteBtn.waitFor({ state: "visible", timeout: 3000 });
      await expect(overwriteBtn).toBeEnabled({ timeout: 3000 });
      await overwriteBtn.click();
    } catch {
      // No overwrite button appeared
    }

    await this.page.keyboard.press("Escape");
    await this.page.waitForTimeout(500);
  }
}