Drop data-title attr; rely on filter({ hasText }) instead

Codecov was flagging data-title={x ?? ""} as a partial-coverage branch
on every card-view variant (Documents.tsx had 3, ModernDocumentItem.tsx
had 1). The fallback was only there because the JSX value can be null
or undefined; both forms (|| and ??) trigger codecov's branch tracker
even with no semantic difference at runtime.

Switching the helpers to the standard Playwright filter-by-text idiom
removes the need for the attribute entirely, which means we can drop
the JSX expression and its branch.

data-testid=document-card and data-processing={String(Boolean(...))}
remain — those are the load-bearing affordances and neither has a
branch codecov tracks.

Author: JSv4

CHANGELOG.md

@@ -11,7 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **VCR.py wrapper for LLM calls in `doc_extract_query_task`** — `opencontractserver/utils/vcr_replay.py` exposes a `maybe_vcr_cassette()` context manager that, when `OC_LLM_VCR_MODE` and `OC_LLM_VCR_CASSETTE` are set on the celery worker, records or replays every HTTP call to LLM provider hosts (currently `api.openai.com` / `api.anthropic.com`). A custom request-body matcher strips volatile values (millisecond timestamps, Django document PKs, OpenAI tool-call IDs, UUIDs) so a cassette recorded against one DB replays cleanly against another. With the env vars unset the wrapper is a no-op — production behavior is unchanged. Pre-recorded cassette for the E2E extract spec lives at `opencontractserver/tests/fixtures/cassettes/e2e_extract_pdf_workflow/extract.yaml`. Replay was verified end-to-end against a deliberately-fake `OPENAI_API_KEY` to confirm no real network call is made. See `docs/development/e2e_vcr.md` for record / replay / debug instructions.
 - **`.github/workflows/frontend-e2e-extract.yml`** — CI workflow (currently `workflow_dispatch` only) that runs the new E2E extract spec against the full `local.yml` stack with `OC_LLM_VCR_MODE=replay` and a fake `OPENAI_API_KEY`. Manual-only because LlamaParse is not yet covered by the cassette and would otherwise be called for real on each run; activating on every PR is a follow-up that needs to extend `_LLM_HOSTS` and re-record.
-- **`frontend/tests/e2e/extract-pdf-workflow.spec.ts`** — full-stack Playwright E2E spec for the extract pipeline: login → create corpus → upload two PDFs (`frontend/tests/fixtures/{usc-title-1,eton-agreement}.pdf`) → wait for parse + embedding → create extract with one column → run with a real OpenAI call → CSV export → assert non-empty cells. Adds new helpers to `frontend/tests/e2e/helpers.ts` (`uploadPdfViaUI`, `waitForDocumentReady`, `createExtractViaUI`, `openExtractByName`, `addColumnViaUI`, `addDocumentsToExtractViaUI`, `runExtractAndWaitForFinish`). Gated on `E2E_RUN_LLM_TESTS=true`; skipped in CI until LLM responses can be mocked over the wire. Runs on the live `local.yml` stack; required tweaks to disable Auth0 (`.envs/.local/.django USE_AUTH0=false`) and to widen the celeryworker `watchfiles --ignore-paths` (in `compose/local/django/celery/worker/start` and the `local.yml` command pointer) so editor / Playwright artifact writes don't hot-reload the worker mid-task. Also adds `data-testid="document-card"` + `data-title` (+ `data-processing` on the `/documents`-view variants) to `frontend/src/views/Documents.tsx` and `data-testid="document-card"` + `data-title` to `frontend/src/components/documents/ModernDocumentItem.tsx`, so tests can poll for the `backendLock` UI signal without depending on hover-only action menus.
+- **`frontend/tests/e2e/extract-pdf-workflow.spec.ts`** — full-stack Playwright E2E spec for the extract pipeline: login → create corpus → upload two PDFs (`frontend/tests/fixtures/{usc-title-1,eton-agreement}.pdf`) → wait for parse + embedding → create extract with one column → run with a real OpenAI call → CSV export → assert non-empty cells. Adds new helpers to `frontend/tests/e2e/helpers.ts` (`uploadPdfViaUI`, `waitForDocumentReady`, `createExtractViaUI`, `openExtractByName`, `addColumnViaUI`, `addDocumentsToExtractViaUI`, `runExtractAndWaitForFinish`). Gated on `E2E_RUN_LLM_TESTS=true`; skipped in CI until LLM responses can be mocked over the wire. Runs on the live `local.yml` stack; required tweaks to disable Auth0 (`.envs/.local/.django USE_AUTH0=false`) and to widen the celeryworker `watchfiles --ignore-paths` (in `compose/local/django/celery/worker/start` and the `local.yml` command pointer) so editor / Playwright artifact writes don't hot-reload the worker mid-task. Also adds `data-testid="document-card"` (+ `data-processing` on the `/documents`-view variants) to `frontend/src/views/Documents.tsx` and `data-testid="document-card"` to `frontend/src/components/documents/ModernDocumentItem.tsx`, so tests can poll for the `backendLock` UI signal without depending on hover-only action menus. Cards are matched by `[data-testid="document-card"]` filtered with the visible title text — the standard Playwright pattern.
 - **Mypy: type analyzer, shared, agents, badges, worker_uploads; introduce shared protocols** (Issue #1335): Brought the five smaller, interface-rich target packages over the ≥70% return-annotation bar called for by the issue and seeded `opencontractserver/types/protocols.py` with the four protocols requested in the scope:
   - `VectorStoreProtocol` — minimum surface (`search` / `async_search`) implemented by `CoreAnnotationVectorStore` (`opencontractserver/llms/vector_stores/core_vector_stores.py`); imported and re-exported from that module so consumers can annotate against the protocol rather than the concrete dataclass.
   - `PipelineComponentProtocol` — `title` / `description` / `author` / `dependencies` surface that the pipeline registry duck-types against; imported from `opencontractserver/pipeline/base/base_component.py` so any future parser/embedder/thumbnailer registered outside the inheritance hierarchy still type-checks against the same contract.

frontend/src/components/documents/ModernDocumentItem.tsx

@@ -1287,7 +1287,6 @@ export const ModernDocumentItem: React.FC<ModernDocumentItemProps> = ({
         <CardContainer
           ref={setNodeRef}
           data-testid="document-card"
-          data-title={title ?? ""}
           className={`${is_selected ? "is-selected" : ""} ${
             isProcessing ? "backend-locked" : ""
           } ${isFailed ? "failed" : ""} ${
@@ -1500,7 +1499,6 @@ export const ModernDocumentItem: React.FC<ModernDocumentItemProps> = ({
       <ListContainer
         ref={setNodeRef}
         data-testid="document-card"
-        data-title={title ?? ""}
         className={`${is_selected ? "is-selected" : ""} ${
           isProcessing ? "backend-locked" : ""
         } ${isFailed ? "failed" : ""} ${isLongPressing ? "long-pressing" : ""}`}

frontend/src/views/Documents.tsx

@@ -1381,7 +1381,6 @@ export const Documents = () => {
                       role="button"
                       tabIndex={0}
                       data-testid="document-card"
-                      data-title={doc.title ?? ""}
                       data-processing={String(Boolean(doc.backendLock))}
                       aria-label={`Open document ${doc.title || "Untitled"}`}
                       $selected={selected_document_ids.includes(doc.id)}
@@ -1506,7 +1505,6 @@ export const Documents = () => {
                       role="row"
                       tabIndex={0}
                       data-testid="document-card"
-                      data-title={doc.title ?? ""}
                       data-processing={String(Boolean(doc.backendLock))}
                       aria-label={`Open document ${doc.title || "Untitled"}`}
                       $selected={selected_document_ids.includes(doc.id)}
@@ -1576,7 +1574,6 @@ export const Documents = () => {
                       role="listitem"
                       tabIndex={0}
                       data-testid="document-card"
-                      data-title={doc.title ?? ""}
                       data-processing={String(Boolean(doc.backendLock))}
                       aria-label={`Open document ${doc.title || "Untitled"}`}
                       $selected={selected_document_ids.includes(doc.id)}

frontend/tests/e2e/helpers.ts

@@ -648,12 +648,13 @@ export async function addColumnViaUI(
  * tab's "Add documents" floating button. Opens SelectDocumentsModal,
  * waits for all document cards to load (graphene returns up to 100 in
  * one page, so all documents appear immediately), clicks each target
- * card by its `data-title` attribute, then confirms with "Add Documents".
+ * card by filtering on its visible title text, then confirms with
+ * "Add Documents".
  *
  * NOTE: The modal's search bar performs full-text content search (not
- * title search). We do NOT use it — we rely on `data-title` selectors
- * directly. All cards are in the DOM and Playwright's `click()` scrolls
- * them into view automatically.
+ * title search). We do NOT use it — we filter cards by visible title
+ * text directly. All cards are in the DOM and Playwright's `click()`
+ * scrolls them into view automatically.
  *
  * If a document is already in the extract, `filterDocIds` removes it
  * from the modal, so it won't appear. The step is skipped gracefully
@@ -691,8 +692,8 @@ export async function addDocumentsToExtractViaUI(
 
   // Wait for at least one document card to load. The query fetches up to
   // RELAY_CONNECTION_MAX_LIMIT (100) in one page, so all cards are in the
-  // DOM immediately. Cards use data-testid="document-card" and
-  // data-title={title} (ModernDocumentItem.tsx).
+  // DOM immediately. Cards are tagged with `data-testid="document-card"`
+  // (ModernDocumentItem.tsx); we then filter by the visible title text.
   await expect(
     page.locator("[data-testid='document-card']").first()
   ).toBeVisible({ timeout: 15_000 });
@@ -701,9 +702,9 @@ export async function addDocumentsToExtractViaUI(
   // the extract and filtered out of the modal by filterDocIds).
   const titlesToAdd: string[] = [];
   for (const title of documentTitles) {
-    const card = page.locator(
-      `[data-testid='document-card'][data-title='${title}']`
-    );
+    const card = page
+      .locator("[data-testid='document-card']")
+      .filter({ hasText: title });
     const count = await card.count();
     if (count > 0) {
       titlesToAdd.push(title);
@@ -718,9 +719,10 @@ export async function addDocumentsToExtractViaUI(
   }
 
   for (const title of titlesToAdd) {
-    const card = page.locator(
-      `[data-testid='document-card'][data-title='${title}']`
-    );
+    const card = page
+      .locator("[data-testid='document-card']")
+      .filter({ hasText: title })
+      .first();
     // click() scrolls the element into view automatically.
     await card.click();
     await page.waitForTimeout(200);
@@ -835,29 +837,26 @@ export async function runExtractAndWaitForFinish(
  * grid view live inside an `opacity: 0` hover-overlay and are never
  * reliably testable without triggering hover interactions.
  *
- * The `data-testid="document-card"` + `data-title` attributes are set
- * on all three card wrapper variants in Documents.tsx (GRID, LIST,
- * COMPACT) and on ModernDocumentItem.tsx for corpus-scoped views.
- *
- * Real-world ingestion can take "up to a few minutes" per PDF; the
- * default 8-minute ceiling leaves headroom for cold workers.
+ * Cards are matched by `data-testid="document-card"` (set in both
+ * Documents.tsx and ModernDocumentItem.tsx) and the visible title
+ * text. Real-world ingestion can take "up to a few minutes" per PDF;
+ * the default 8-minute ceiling leaves headroom for cold workers.
  */
 export async function waitForDocumentReady(
   page: Page,
   documentTitle: string,
   timeoutMs: number = 8 * 60 * 1000
 ): Promise<void> {
-  // Use attribute selector to match the exact title (avoids partial-text
-  // collisions when one title is a prefix of another).
-  const cardSelector = `[data-testid="document-card"][data-title="${documentTitle}"]`;
-
   await expect(async () => {
     // Re-navigate on every attempt to force a fresh GraphQL fetch and
     // bypass any in-flight polling gaps.
     await spaNavigate(page, "/documents");
     await expectViewVisible(page, { kind: "text", text: /Your\s+documents/i });
 
-    const card = page.locator(cardSelector);
+    const card = page
+      .locator("[data-testid='document-card']")
+      .filter({ hasText: documentTitle })
+      .first();
     await expect(card).toBeVisible({ timeout: 10_000 });
 
     // `data-processing="true"` while backendLock === true.