Skip to content

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

Python
11.8 KB
Raw Blame
import { describe, expect, it } from "vitest";
import type {
  TaskFailurePhase,
  TaskFileEntry,
} from "@/app/api/queries/useGetTasksQuery";
import {
  analyzeTaskFileIngestionFailure,
  buildRowStatusLabel,
  FILE_ERROR_MAX_LINE_LENGTH,
  formatApiComponent,
  getTaskFailureToastDescription,
  normalizeFailurePhase,
  resolveTaskFileError,
} from "./task-error-display";

/**
 * Chosen by churn: 3 of this file's 9 commits in the last year were bug fixes
 * (#2152 "provide real error for onboarding apiKey setup and settings", #2127
 * "surface provider errors in chat instead of generic connection failures",
 * #1771 "cancel case not retryable"), plus #1769 which added skipped-task
 * warnings.
 *
 * `formatProviderErrorMessage` is deliberately NOT stubbed — the #2127 fix is
 * precisely that these messages get run through it, so the real function is
 * part of what is under test.
 */

function entry(overrides: Partial<TaskFileEntry> = {}): TaskFileEntry {
  return { status: "failed", ...overrides };
}

// A real _update_by_query 409 as opensearch-py renders it: the whole response
// body becomes the exception message, because that response carries no
// top-level "error" key for the client to use instead (#2349).
const OPENSEARCH_CONFLICT_ERROR =
  'ConflictError(409, \'{"took":2719,"timed_out":false,"total":300,' +
  '"updated":19,"version_conflicts":1,"failures":[{"index":"documents",' +
  '"id":"20","cause":{"type":"version_conflict_engine_exception"}}]}\')';

const BACKEND_CLASSIFIED_MESSAGE =
  "The search index was busy and this change conflicted with another " +
  "update. Nothing is wrong with the file — retry ingestion.";

describe("formatApiComponent", () => {
  it("maps every known component to its display label", () => {
    expect(formatApiComponent("docling")).toBe("Docling");
    expect(formatApiComponent("openrag")).toBe("OpenRAG");
    expect(formatApiComponent("langflow")).toBe("Langflow");
    expect(formatApiComponent("opensearch")).toBe("OpenSearch");
  });

  it("returns undefined when no component is given", () => {
    expect(formatApiComponent(undefined)).toBeUndefined();
  });
});

describe("normalizeFailurePhase", () => {
  it("accepts every known phase", () => {
    for (const phase of [
      "parsing",
      "chunking",
      "embedding",
      "indexing",
      "file_validation",
      "cancelled",
      "unknown",
    ]) {
      expect(normalizeFailurePhase(phase)).toBe(phase);
    }
  });

  it("rejects unknown or missing phases", () => {
    expect(normalizeFailurePhase("teleporting")).toBeUndefined();
    expect(normalizeFailurePhase("")).toBeUndefined();
    expect(normalizeFailurePhase(undefined)).toBeUndefined();
  });
});

describe("buildRowStatusLabel", () => {
  it("uses bespoke wording for cancelled, validation and unknown (#1771)", () => {
    expect(buildRowStatusLabel("cancelled")).toBe("Cancelled");
    expect(buildRowStatusLabel("file_validation")).toBe(
      "File validation issue",
    );
    expect(buildRowStatusLabel("unknown")).toBe("Failed");
  });

  it("suffixes pipeline phases with 'issue'", () => {
    expect(buildRowStatusLabel("parsing")).toBe("Parsing issue");
    expect(buildRowStatusLabel("embedding")).toBe("Embedding issue");
  });
});

describe("resolveTaskFileError", () => {
  it("prefers a result warning over everything else (#1769)", () => {
    const message = resolveTaskFileError(
      entry({
        result: { warning: "Skipped: unsupported page" },
        user_facing_message: "ignored",
        error: "ignored too",
      }),
      "task level ignored",
    );

    expect(message).toContain("unsupported page");
  });

  it("falls back to user_facing_message, then error, then task error (#2152)", () => {
    expect(
      resolveTaskFileError(
        entry({ user_facing_message: "Invalid API key", error: "raw" }),
        "task",
      ),
    ).toBe("Invalid API key");

    expect(resolveTaskFileError(entry({ error: "raw failure" }), "task")).toBe(
      "raw failure",
    );

    expect(resolveTaskFileError(entry({}), "task level boom")).toBe(
      "task level boom",
    );
  });

  it("skips blank candidates rather than returning empty text", () => {
    expect(
      resolveTaskFileError(
        entry({
          result: { warning: "   " },
          user_facing_message: "  ",
          error: "  ",
        }),
        "  ",
      ),
    ).toBe("Unknown error");
  });

  it("ignores a result object without a string warning", () => {
    expect(
      resolveTaskFileError(entry({ result: { warning: 42 }, error: "real" })),
    ).toBe("real");
  });

  it("returns Unknown error when nothing is available", () => {
    expect(resolveTaskFileError(entry({}))).toBe("Unknown error");
  });

  it("runs messages through provider-error formatting (#2127)", () => {
    // A raw provider JSON blob must not reach the UI verbatim.
    const message = resolveTaskFileError(
      entry({ error: '{"message": "Rate limit exceeded"}' }),
    );

    expect(message).not.toContain("{");
    expect(message).toContain("Rate limit exceeded");
  });

  it("prefers the backend's classified message over a raw payload (#2349)", () => {
    // This precedence is what makes the backend classifier work at all. If these
    // checks are ever reordered, a classified OpenSearch failure would fall back
    // to the raw payload and be mangled again.
    expect(
      resolveTaskFileError(
        entry({
          error: OPENSEARCH_CONFLICT_ERROR,
          user_facing_message: BACKEND_CLASSIFIED_MESSAGE,
        }),
      ),
    ).toBe(BACKEND_CLASSIFIED_MESSAGE);
  });

  it("passes a clean sentence through the provider parser unchanged (#2349)", () => {
    // The message contains no JSON, so the chat provider-error parser must not
    // rewrite or truncate it.
    expect(
      resolveTaskFileError(
        entry({ user_facing_message: BACKEND_CLASSIFIED_MESSAGE }),
      ),
    ).toBe(BACKEND_CLASSIFIED_MESSAGE);
  });

  it("keeps the whole raw error when the backend did not classify it (#2349)", () => {
    // Regression guard: this used to collapse to the 20-character fragment
    // "ConflictError(409, '", discarding the failures[] array that names the
    // index, shard and document — the only way to diagnose the failure.
    const resolved = resolveTaskFileError(
      entry({ error: OPENSEARCH_CONFLICT_ERROR }),
    );

    expect(resolved).toBe(OPENSEARCH_CONFLICT_ERROR);
    expect(resolved).toContain("version_conflict_engine_exception");
  });
});

describe("getTaskFailureToastDescription", () => {
  it("uses the first meaningful failed-file message", () => {
    const description = getTaskFailureToastDescription({
      files: {
        "ok.pdf": entry({ status: "completed" }),
        "bad.pdf": entry({ status: "failed", error: "parser died" }),
      },
    });

    expect(description).toBe("parser died");
  });

  it("treats status 'error' as failed too", () => {
    expect(
      getTaskFailureToastDescription({
        files: { "a.pdf": entry({ status: "error", error: "boom" }) },
      }),
    ).toBe("boom");
  });

  it("skips files whose message resolves to Unknown error", () => {
    const description = getTaskFailureToastDescription({
      files: {
        "a.pdf": entry({ status: "failed" }),
        "b.pdf": entry({ status: "failed", error: "real reason" }),
      },
    });

    expect(description).toBe("real reason");
  });

  it("falls back to the task-level error", () => {
    expect(
      getTaskFailureToastDescription({ error: "  task blew up  ", files: {} }),
    ).toBe("task blew up");
  });

  it("falls back to a failed-file count, pluralized", () => {
    expect(getTaskFailureToastDescription({ failed_files: 1 })).toBe(
      "1 file failed",
    );
    expect(getTaskFailureToastDescription({ failed_files: 3 })).toBe(
      "3 files failed",
    );
  });

  it("derives the count from files when failed_files is absent", () => {
    expect(
      getTaskFailureToastDescription({
        files: {
          "a.pdf": entry({ status: "failed" }),
          "b.pdf": entry({ status: "error" }),
          "c.pdf": entry({ status: "completed" }),
        },
      }),
    ).toBe("2 files failed");
  });

  it("returns Unknown error for a task with nothing to report", () => {
    expect(getTaskFailureToastDescription({})).toBe("Unknown error");
    expect(getTaskFailureToastDescription({ error: null, files: null })).toBe(
      "Unknown error",
    );
  });
});

describe("analyzeTaskFileIngestionFailure", () => {
  it("marks earlier pipeline steps completed and the failing one failed", () => {
    const analysis = analyzeTaskFileIngestionFailure(
      entry({ failure_phase: "embedding", error: "vector store down" }),
    );

    expect(analysis.failedStep).toBe("embedding");
    expect(analysis.pipelineSteps).toEqual([
      { id: "parsing", label: "Parsing", status: "completed" },
      { id: "chunking", label: "Chunking", status: "completed" },
      { id: "embedding", label: "Embedding", status: "failed" },
    ]);
    expect(analysis.rowStatusLabel).toBe("Embedding issue");
    expect(analysis.failureSummary).toBe("Failed at embedding");
  });

  it("shows only the failing step for parsing", () => {
    const analysis = analyzeTaskFileIngestionFailure(
      entry({ failure_phase: "parsing" }),
    );

    expect(analysis.pipelineSteps).toEqual([
      { id: "parsing", label: "Parsing", status: "failed" },
    ]);
  });

  it("collapses cancelled to a single step with no pipeline (#1771)", () => {
    const analysis = analyzeTaskFileIngestionFailure(
      entry({ failure_phase: "cancelled" }),
    );

    expect(analysis.pipelineSteps).toEqual([
      { id: "cancelled", label: "Cancelled", status: "failed" },
    ]);
    expect(analysis.rowStatusLabel).toBe("Cancelled");
    expect(analysis.failureSummary).toBe("Cancelled");
  });

  it("collapses file_validation to a single step", () => {
    const analysis = analyzeTaskFileIngestionFailure(
      entry({ failure_phase: "file_validation" }),
    );

    expect(analysis.pipelineSteps).toEqual([
      { id: "file_validation", label: "File validation", status: "failed" },
    ]);
  });

  it("defaults an unrecognized phase to unknown", () => {
    const analysis = analyzeTaskFileIngestionFailure(
      // Cast deliberately: TaskFailurePhase is a closed union, but the backend
      // can send a phase this frontend build has never heard of. That is the
      // case normalizeFailurePhase exists to absorb, so it must be tested.
      entry({ failure_phase: "teleporting" as TaskFailurePhase }),
    );

    expect(analysis.failedStep).toBe("unknown");
    expect(analysis.pipelineSteps).toEqual([
      { id: "unknown", label: "Ingestion", status: "failed" },
    ]);
    expect(analysis.rowStatusLabel).toBe("Failed");
  });

  it("tags the failing component when the API reports one", () => {
    const analysis = analyzeTaskFileIngestionFailure(
      entry({ failure_phase: "indexing", component: "opensearch" }),
    );

    expect(analysis.componentCause).toBe("OpenSearch");
    expect(analysis.componentTags).toEqual(["OpenSearch"]);
  });

  it("leaves component tags empty when none is reported", () => {
    const analysis = analyzeTaskFileIngestionFailure(entry({}));

    expect(analysis.componentCause).toBeUndefined();
    expect(analysis.componentTags).toEqual([]);
  });

  it("truncates a long summary line with an ellipsis", () => {
    const analysis = analyzeTaskFileIngestionFailure(
      entry({ error: "x".repeat(200) }),
    );

    expect(analysis.summaryLine).toHaveLength(FILE_ERROR_MAX_LINE_LENGTH);
    expect(analysis.summaryLine.endsWith("…")).toBe(true);
    // The full message stays available for the expanded view.
    expect(analysis.resolvedError).toHaveLength(200);
  });

  it("leaves a short summary line untouched", () => {
    const analysis = analyzeTaskFileIngestionFailure(
      entry({ error: "short message" }),
    );

    expect(analysis.summaryLine).toBe("short message");
  });
});