@capagents/forgeqe 0.0.0-stage → 1.0.0

package/src/cases/files.ts

@@ -0,0 +1,295 @@
+import { readFileSync } from "node:fs"
+import path from "node:path"
+
+import YAML from "yaml"
+
+import type { CaseStep, TestCase } from "./types.ts"
+
+/** A goal typed or passed as plain text: one test case, the text is its description. */
+export function textCase(text: string, n = 1): TestCase {
+  const body = text.trim()
+  const [first, ...rest] = body.split("\n")
+  return {
+    id: `text#${n}`,
+    title: clip(first.replace(/^#+\s*/, "").trim(), 100),
+    source: "text",
+    description: rest.join("\n").trim() || (first.length > 100 ? body : undefined),
+    steps: [],
+  }
+}
+
+/** Test cases from a file: .yaml/.yml/.json, .csv, .feature (Gherkin), or any text file split on `---` lines. */
+export function fileCases(file: string): TestCase[] {
+  const text = readFileSync(file, "utf8")
+  const base = path.basename(file)
+  const ext = path.extname(file).toLowerCase()
+  const cases =
+    ext === ".yaml" || ext === ".yml" || ext === ".json"
+      ? structuredCases(ext === ".json" ? JSON.parse(text) : YAML.parse(text), base)
+      : ext === ".csv"
+        ? csvCases(text, base)
+        : ext === ".feature"
+          ? featureCases(text, base)
+          : textFileCases(text, base)
+  if (!cases.length) throw new Error(`No test cases in ${file}.`)
+  return cases
+}
+
+function textFileCases(text: string, base: string): TestCase[] {
+  return text
+    .split(/^\s*-{3,}\s*$/m)
+    .map((block) => block.trim())
+    .filter(Boolean)
+    .map((block, i) => ({ ...textCase(block, i + 1), id: `${base}#${i + 1}`, source: "file" as const }))
+}
+
+// -- YAML / JSON --------------------------------------------------------------------------------
+
+type Raw = Record<string, unknown>
+
+function structuredCases(doc: unknown, base: string): TestCase[] {
+  const items = Array.isArray(doc) ? doc : Array.isArray((doc as Raw)?.cases) ? ((doc as Raw).cases as unknown[]) : doc ? [doc] : []
+  return items.map((item, i) => {
+    if (typeof item === "string") return { ...textCase(item, i + 1), id: `${base}#${i + 1}`, source: "file" as const }
+    const raw = (item || {}) as Raw
+    const steps = Array.isArray(raw.steps) ? raw.steps.map(stepFrom).filter((s): s is CaseStep => !!s) : []
+    const description = str(raw.description) || str(raw.goal)
+    const title = str(raw.title) || str(raw.name) || (description ? clip(description.split("\n")[0], 100) : `Case ${i + 1}`)
+    return {
+      id: str(raw.id) || `${base}#${i + 1}`,
+      title,
+      source: "file" as const,
+      description: description && description !== title ? description : undefined,
+      preconditions: list(raw.preconditions),
+      steps,
+      startUrl: str(raw.url) || str(raw.start_url),
+      tags: list(raw.tags),
+      group: str(raw.group) || str(raw.suite) || str(raw.area),
+      requirements: list(raw.requirements) || list(raw.refs),
+    }
+  })
+}
+
+function stepFrom(raw: unknown): CaseStep | null {
+  if (typeof raw === "string") return raw.trim() ? { action: raw.trim() } : null
+  const r = (raw || {}) as Raw
+  const action = str(r.action) || str(r.step)
+  if (!action) return null
+  return { action, data: str(r.data), expected: str(r.expected) || str(r.result) }
+}
+
+// -- CSV ------------------------------------------------------------------------------------------
+
+/**
+ * Header row, then one row per case or per step: `id, title, url, description, preconditions, tags, action, data,
+ * expected`. A row with an empty id, or the same id as the row above, adds a step to that case.
+ */
+function csvCases(text: string, base: string): TestCase[] {
+  const rows = parseCsv(text)
+  if (rows.length < 2) return []
+  const header = rows[0].map((h) => h.trim().toLowerCase().replace(/[\s-]+/g, "_"))
+  const col = (row: string[], ...names: string[]) => {
+    for (const n of names) {
+      const i = header.indexOf(n)
+      if (i >= 0 && row[i]?.trim()) return row[i].trim()
+    }
+    return undefined
+  }
+  const cases: TestCase[] = []
+  for (const row of rows.slice(1)) {
+    if (row.every((c) => !c.trim())) continue
+    const id = col(row, "id", "key", "test_id")
+    const last = cases[cases.length - 1]
+    const step: CaseStep | null = col(row, "action", "step")
+      ? { action: col(row, "action", "step")!, data: col(row, "data", "test_data"), expected: col(row, "expected", "expected_result", "result") }
+      : null
+    if (last && (!id || id === last.id)) {
+      if (step) last.steps.push(step)
+      continue
+    }
+    const description = col(row, "description", "goal", "steps")
+    const title = col(row, "title", "name", "summary") || (description ? clip(description.split("\n")[0], 100) : `Case ${cases.length + 1}`)
+    cases.push({
+      id: id || `${base}#${cases.length + 1}`,
+      title,
+      source: "file",
+      description: description && description !== title ? description : undefined,
+      preconditions: splitList(col(row, "preconditions", "precondition")),
+      steps: step ? [step] : [],
+      startUrl: col(row, "url", "start_url"),
+      tags: splitList(col(row, "tags", "labels")),
+      group: col(row, "group", "suite", "area"),
+      requirements: splitList(col(row, "requirements", "refs")),
+    })
+  }
+  return cases
+}
+
+/** RFC 4180: quoted fields, doubled quotes, newlines inside quotes. */
+export function parseCsv(text: string): string[][] {
+  const rows: string[][] = []
+  let row: string[] = []
+  let field = ""
+  let quoted = false
+  const src = text.replace(/^\uFEFF/, "")
+  for (let i = 0; i < src.length; i++) {
+    const c = src[i]
+    if (quoted) {
+      if (c === '"' && src[i + 1] === '"') {
+        field += '"'
+        i++
+      } else if (c === '"') quoted = false
+      else field += c
+      continue
+    }
+    if (c === '"') quoted = true
+    else if (c === ",") {
+      row.push(field)
+      field = ""
+    } else if (c === "\n" || c === "\r") {
+      if (c === "\r" && src[i + 1] === "\n") i++
+      row.push(field)
+      rows.push(row)
+      row = []
+      field = ""
+    } else field += c
+  }
+  if (field || row.length) {
+    row.push(field)
+    rows.push(row)
+  }
+  return rows
+}
+
+// -- Gherkin ------------------------------------------------------------------------------------
+
+const STEP_KEYWORDS = ["Given", "When", "Then", "And", "But", "*"]
+
+/** Each Scenario is a case; a Scenario Outline gives one case per Examples row. Then-steps are expected results. */
+function featureCases(text: string, base: string): TestCase[] {
+  type Scenario = { name: string; tags: string[]; steps: string[]; examples: string[][] }
+  let feature = ""
+  let featureTags: string[] = []
+  let pendingTags: string[] = []
+  let background: string[] = []
+  let current: Scenario | null = null
+  let inBackground = false
+  let inExamples = false
+  let docString: string | null = null
+  const scenarios: Scenario[] = []
+
+  const appendToLastStep = (extra: string) => {
+    const target = inBackground ? background : current?.steps
+    if (target?.length) target[target.length - 1] += `\n${extra}`
+  }
+
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim()
+    if (docString !== null) {
+      if (line === '"""' || line === "```") {
+        appendToLastStep(docString.trimEnd())
+        docString = null
+      } else docString += `${line}\n`
+      continue
+    }
+    if (!line || line.startsWith("#")) continue
+    if (line === '"""' || line === "```") {
+      docString = ""
+      continue
+    }
+    if (line.startsWith("@")) {
+      pendingTags.push(...line.split(/\s+/).map((t) => t.slice(1)).filter(Boolean))
+      continue
+    }
+    const keyword = line.match(/^(Feature|Background|Scenario Outline|Scenario Template|Scenario|Example|Examples|Scenarios|Rule):\s*(.*)$/)
+    if (keyword) {
+      const [, kind, name] = keyword
+      inBackground = false
+      inExamples = false
+      if (kind === "Feature") {
+        feature = name
+        featureTags = pendingTags
+      } else if (kind === "Background") inBackground = true
+      else if (kind === "Examples" || kind === "Scenarios") inExamples = true
+      else if (kind !== "Rule") {
+        current = { name, tags: [...featureTags, ...pendingTags], steps: [], examples: [] }
+        scenarios.push(current)
+      }
+      pendingTags = []
+      continue
+    }
+    if (line.startsWith("|")) {
+      const cells = line.slice(1, line.endsWith("|") ? -1 : undefined).split("|").map((c) => c.trim())
+      if (inExamples && current) current.examples.push(cells)
+      else appendToLastStep(line)
+      continue
+    }
+    const kw = STEP_KEYWORDS.find((k) => line === k || line.startsWith(`${k} `))
+    if (kw) {
+      if (inBackground) background.push(line)
+      else current?.steps.push(line)
+    }
+  }
+
+  const cases: TestCase[] = []
+  for (const sc of scenarios) {
+    const header = sc.examples[0]
+    const rows = header ? sc.examples.slice(1) : [[]]
+    rows.forEach((row, r) => {
+      const fill = (s: string) => (header ? header.reduce((acc, h, i) => acc.split(`<${h}>`).join(row[i] ?? ""), s) : s)
+      const n = cases.length + 1
+      cases.push({
+        id: `${base}#${n}`,
+        title: fill(sc.name) + (header && !sc.name.includes("<") ? ` (example ${r + 1})` : ""),
+        source: "file",
+        description: feature ? `Feature: ${feature}` : undefined,
+        steps: gherkinSteps([...background, ...sc.steps].map(fill)),
+        tags: sc.tags.length ? sc.tags : undefined,
+      })
+    })
+  }
+  return cases
+}
+
+function gherkinSteps(lines: string[]): CaseStep[] {
+  const steps: CaseStep[] = []
+  let inThen = false
+  for (const line of lines) {
+    const kw = STEP_KEYWORDS.find((k) => line === k || line.startsWith(`${k} `))!
+    if (kw === "Then") inThen = true
+    else if (kw === "Given" || kw === "When") inThen = false
+    if (inThen) {
+      const last = steps[steps.length - 1]
+      if (last) last.expected = last.expected ? `${last.expected}\n${line}` : line
+      else steps.push({ action: "Check the page", expected: line })
+    } else steps.push({ action: line })
+  }
+  return steps
+}
+
+// -- helpers ------------------------------------------------------------------------------------
+
+function str(v: unknown): string | undefined {
+  if (v === undefined || v === null) return undefined
+  const s = String(v).trim()
+  return s || undefined
+}
+
+function list(v: unknown): string[] | undefined {
+  if (Array.isArray(v)) {
+    const out = v.map((x) => String(x).trim()).filter(Boolean)
+    return out.length ? out : undefined
+  }
+  return splitList(str(v))
+}
+
+function splitList(v?: string): string[] | undefined {
+  if (!v) return undefined
+  const out = v.split(/[;\n]/).map((s) => s.trim()).filter(Boolean)
+  return out.length ? out : undefined
+}
+
+export function clip(s: string, n: number): string {
+  const one = s.replace(/\s+/g, " ").trim()
+  return one.length <= n ? one : `${one.slice(0, n - 1)}…`
+}

package/src/cases/goal.ts

@@ -0,0 +1,53 @@
+import type { TestCase } from "./types.ts"
+
+const SOURCE_NAME = { text: "text", file: "file", ado: "Azure DevOps", jira: "Jira", xray: "Xray", testrail: "TestRail", zephyr: "Zephyr Scale", qtest: "qTest" } as const
+
+/**
+ * The browser goal for a test case: every step with its data and expected result, and an instruction to check each
+ * expected result on the page. The agent's own verdict on those checks decides pass or fail.
+ */
+export function goalFor(tc: TestCase): string {
+  const lines = [`Test case ${tc.id}: ${tc.title}`]
+  if (tc.description?.trim()) lines.push("", tc.description.trim())
+  if (tc.preconditions?.length) {
+    lines.push("", "Preconditions:")
+    for (const p of tc.preconditions) lines.push(`- ${p}`)
+  }
+  if (tc.steps.length) {
+    lines.push("", "Steps:")
+    tc.steps.forEach((s, i) => {
+      lines.push(`${i + 1}. ${s.action}`)
+      if (s.data?.trim()) lines.push(`   Data: ${s.data.trim()}`)
+      if (s.expected?.trim()) lines.push(`   Expected: ${s.expected.trim()}`)
+    })
+  }
+  const checks = tc.steps.some((s) => s.expected?.trim())
+  lines.push(
+    "",
+    checks
+      ? "Carry out the steps in order and check every expected result on the page. Finish with success only if every expected result holds; otherwise finish with failure and say which step's expected result did not hold and what the page showed instead."
+      : "Carry out the test case and check that the outcome it describes holds on the page. Finish with success only if it does; otherwise finish with failure and say what the page showed instead.",
+  )
+  return lines.join("\n")
+}
+
+/** Markdown for the coding agent's handoff: where the case came from and what it checks. */
+export function caseMarkdown(tc: TestCase): string {
+  const lines = ["## Test case", "", `${tc.id}: ${tc.title}`, `Source: ${SOURCE_NAME[tc.source]}${tc.url ? ` (${tc.url})` : ""}`]
+  if (tc.tags?.length) lines.push(`Tags: ${tc.tags.join(", ")}`)
+  if (tc.description?.trim()) lines.push("", tc.description.trim())
+  if (tc.preconditions?.length) lines.push("", "Preconditions:", ...tc.preconditions.map((p) => `- ${p}`))
+  if (tc.steps.length) {
+    lines.push("", "| # | Action | Data | Expected |", "|---|--------|------|----------|")
+    tc.steps.forEach((s, i) => lines.push(`| ${i + 1} | ${cell(s.action)} | ${cell(s.data)} | ${cell(s.expected)} |`))
+  }
+  lines.push(
+    "",
+    `Name the test after the case, e.g. \`${tc.id} ${tc.title}\`, and assert each expected result. Keep the id in the test title so results can be traced back to ${SOURCE_NAME[tc.source]}.`,
+  )
+  return lines.join("\n")
+}
+
+function cell(s?: string): string {
+  return (s || "").replace(/\|/g, "\\|").replace(/\s*\n\s*/g, "<br>")
+}

package/src/cases/http.ts

@@ -0,0 +1,111 @@
+/** JSON over HTTP for the test-management APIs. Errors name the method, URL path, and status, never credentials. */
+export async function http<T = unknown>(
+  url: string,
+  opts: { method?: string; auth: string; body?: unknown; contentType?: string; headers?: Record<string, string> },
+): Promise<{ data: T; headers: Headers }> {
+  const res = await fetch(url, {
+    method: opts.method || (opts.body === undefined ? "GET" : "POST"),
+    headers: {
+      Accept: "application/json",
+      ...(opts.auth ? { Authorization: opts.auth } : {}),
+      ...(opts.body === undefined ? {} : { "Content-Type": opts.contentType || "application/json" }),
+      ...opts.headers,
+    },
+    body: opts.body === undefined ? undefined : typeof opts.body === "string" ? opts.body : JSON.stringify(opts.body),
+  })
+  const text = await res.text()
+  if (!res.ok) {
+    const where = new URL(url)
+    const hint = res.status === 401 || res.status === 403 ? " Check the token and its permissions." : ""
+    throw new Error(`${opts.method || (opts.body === undefined ? "GET" : "POST")} ${where.host}${where.pathname} failed: ${res.status} ${res.statusText}.${hint} ${brief(text)}`.trim())
+  }
+  let data: unknown = text
+  try {
+    data = text ? JSON.parse(text) : null
+  } catch {}
+  return { data: data as T, headers: res.headers }
+}
+
+function brief(text: string): string {
+  const one = text.replace(/\s+/g, " ").trim()
+  return one.length > 300 ? `${one.slice(0, 300)}…` : one
+}
+
+export function basic(user: string, secret: string): string {
+  return `Basic ${Buffer.from(`${user}:${secret}`).toString("base64")}`
+}
+
+export function envSecret(name: string, what: string): string {
+  const value = process.env[name]
+  if (!value) throw new Error(`${what} needs ${name} in the environment (or a .env next to forgeqe.yaml), or a sign-in: run forgeqe auth login, or type /auth in the shell.`)
+  return value
+}
+
+/** Rich text from Azure DevOps (HTML, often entity-encoded) as plain text with line breaks. */
+export function htmlToText(html: string | undefined): string {
+  if (!html) return ""
+  const decoded = decodeEntities(html)
+  return decodeEntities(
+    decoded
+      .replace(/<\s*br\s*\/?>/gi, "\n")
+      .replace(/<\s*\/\s*(p|div|li|tr|h[1-6])\s*>/gi, "\n")
+      .replace(/<\s*li[^>]*>/gi, "- ")
+      .replace(/<[^>]+>/g, ""),
+  )
+    .split("\n")
+    .map((l) => l.replace(/[ \t\u00a0]+/g, " ").trim())
+    .filter(Boolean)
+    .join("\n")
+}
+
+function decodeEntities(s: string): string {
+  return s
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;|&apos;/g, "'")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&#(\d+);/g, (_, n) => String.fromCodePoint(Number(n)))
+    .replace(/&#x([0-9a-f]+);/gi, (_, n) => String.fromCodePoint(parseInt(n, 16)))
+    .replace(/&amp;/g, "&")
+}
+
+type AdfNode = { type?: string; text?: string; content?: AdfNode[]; attrs?: Record<string, unknown> }
+
+/** Jira Cloud's Atlassian Document Format as plain text. Strings (Jira Server wiki text) pass through. */
+export function adfToText(doc: unknown): string {
+  if (typeof doc === "string") return doc.trim()
+  if (!doc || typeof doc !== "object") return ""
+  const out: string[] = []
+  const walk = (node: AdfNode, prefix = ""): string => {
+    if (node.type === "text") return node.text || ""
+    if (node.type === "hardBreak") return "\n"
+    const inner = (node.content || []).map((c) => walk(c, prefix)).join("")
+    switch (node.type) {
+      case "paragraph":
+      case "heading":
+        return `${inner}\n`
+      case "listItem":
+        return `- ${inner.trim()}\n`
+      case "codeBlock":
+        return `${inner}\n`
+      default:
+        return inner
+    }
+  }
+  out.push(walk(doc as AdfNode))
+  return out.join("").split("\n").map((l) => l.trimEnd()).filter((l, i, a) => l || (i > 0 && a[i - 1])).join("\n").trim()
+}
+
+/** Plain text (paragraphs separated by blank lines) as an ADF document for Jira Cloud comments. */
+export function textToAdf(text: string): Record<string, unknown> {
+  const paragraphs = text.split(/\n{2,}/).map((p) => p.trim()).filter(Boolean)
+  return {
+    type: "doc",
+    version: 1,
+    content: paragraphs.map((p) => ({
+      type: "paragraph",
+      content: p.split("\n").flatMap((line, i) => [...(i ? [{ type: "hardBreak" }] : []), { type: "text", text: line }]),
+    })),
+  }
+}

package/src/cases/index.ts

@@ -0,0 +1,131 @@
+import { existsSync, statSync } from "node:fs"
+import path from "node:path"
+
+import type { SourcesConfig } from "../config.ts"
+import { adoCases, adoWriteBack } from "./ado.ts"
+import { fileCases, textCase } from "./files.ts"
+import { jiraCases, jiraWriteBack } from "./jira.ts"
+import { qtestCases, qtestWriteBack } from "./qtest.ts"
+import { testrailCases, testrailWriteBack } from "./testrail.ts"
+import type { CaseResult, TestCase, WriteBack } from "./types.ts"
+import { xrayCases, xrayWriteBack } from "./xray.ts"
+import { zephyrCases, zephyrWriteBack } from "./zephyr.ts"
+
+export { caseMarkdown, goalFor } from "./goal.ts"
+export type { CaseResult, CaseStatus, CaseStep, TestCase, WriteBack } from "./types.ts"
+
+/**
+ * Where a reference points: `ado:…`, `jira:…`, `xray:…`, `testrail:…`, `zephyr:…`, `qtest:…`, an existing file, or
+ * otherwise plain text that is itself the test case.
+ */
+export function refKind(ref: string): "ado" | "jira" | "xray" | "testrail" | "zephyr" | "qtest" | "file" | "text" {
+  const scheme = ref.match(/^(ado|azure|jira|xray|testrail|zephyr|qtest):/i)?.[1]?.toLowerCase()
+  if (scheme === "ado" || scheme === "azure") return "ado"
+  if (scheme) return scheme as "jira" | "xray" | "testrail" | "zephyr" | "qtest"
+  const file = path.resolve(ref)
+  if (ref.length < 1024 && existsSync(file) && statSync(file).isFile()) return "file"
+  return "text"
+}
+
+export async function loadCases(refs: string[], cfg: SourcesConfig): Promise<TestCase[]> {
+  const cases: TestCase[] = []
+  let texts = 0
+  for (const ref of refs.map((r) => r.trim()).filter(Boolean)) {
+    const kind = refKind(ref)
+    const rest = ref.slice(ref.indexOf(":") + 1).trim()
+    if (kind === "ado") cases.push(...(await adoCases(rest, cfg)))
+    else if (kind === "jira") cases.push(...(await jiraCases(rest, cfg)))
+    else if (kind === "xray") cases.push(...(await xrayCases(rest, cfg)))
+    else if (kind === "testrail") cases.push(...(await testrailCases(rest, cfg)))
+    else if (kind === "zephyr") cases.push(...(await zephyrCases(rest, cfg)))
+    else if (kind === "qtest") cases.push(...(await qtestCases(rest, cfg)))
+    else if (kind === "file") cases.push(...fileCases(path.resolve(ref)))
+    else cases.push(textCase(ref, ++texts))
+  }
+  return uniqueIds(cases)
+}
+
+/** Where the agent wants test cases from, as it decided from the user's request. */
+export type CaseSelector = {
+  source: "azure_devops" | "jira" | "xray" | "testrail" | "zephyr" | "qtest" | "file" | "text"
+  ids?: string[]
+  plan?: string
+  suite?: string
+  run?: string
+  cycle?: string
+  folder?: string
+  jql?: string
+  paths?: string[]
+  text?: string
+}
+
+/** Test cases for structured selectors; relative paths resolve against `cwd`. */
+export async function casesFrom(selectors: CaseSelector[], cfg: SourcesConfig, cwd = process.cwd()): Promise<TestCase[]> {
+  const cases: TestCase[] = []
+  let texts = 0
+  const ids = (s: CaseSelector, what: string) => {
+    const list = (s.ids || []).map((i) => String(i).trim()).filter(Boolean)
+    if (!list.length) throw new Error(`${what}: give ids, a plan, or a query.`)
+    return list.join(",")
+  }
+  for (const s of selectors) {
+    if (s.source === "azure_devops") {
+      cases.push(...(await adoCases(s.plan ? `plan=${s.plan}${s.suite ? `/suite=${s.suite}` : ""}` : ids(s, "Azure DevOps"), cfg)))
+    } else if (s.source === "jira") {
+      cases.push(...(await jiraCases(s.jql ? `jql=${s.jql}` : ids(s, "Jira"), cfg)))
+    } else if (s.source === "xray") {
+      cases.push(...(await xrayCases(s.plan ? `plan=${s.plan}` : s.jql ? `jql=${s.jql}` : ids(s, "Xray"), cfg)))
+    } else if (s.source === "testrail") {
+      const sel = s.run ? `run=${s.run}` : s.plan ? `plan=${s.plan}` : s.suite ? `suite=${s.suite}` : ids(s, "TestRail")
+      cases.push(...(await testrailCases(sel, cfg)))
+    } else if (s.source === "zephyr") {
+      cases.push(...(await zephyrCases(s.cycle ? `cycle=${s.cycle}` : s.folder ? `folder=${s.folder}` : ids(s, "Zephyr Scale"), cfg)))
+    } else if (s.source === "qtest") {
+      cases.push(...(await qtestCases(s.cycle ? `cycle=${s.cycle}` : s.suite ? `suite=${s.suite}` : ids(s, "qTest"), cfg)))
+    } else if (s.source === "file") {
+      if (!s.paths?.length) throw new Error("File source: give the file paths.")
+      for (const p of s.paths) {
+        const file = path.resolve(cwd, p)
+        if (!existsSync(file) || !statSync(file).isFile()) throw new Error(`Test case file not found: ${file}`)
+        cases.push(...fileCases(file))
+      }
+    } else {
+      if (!s.text?.trim()) throw new Error("Text source: give the test case text.")
+      cases.push(textCase(s.text, ++texts))
+    }
+  }
+  return uniqueIds(cases)
+}
+
+function uniqueIds(cases: TestCase[]): TestCase[] {
+  const seen = new Map<string, number>()
+  return cases.map((c) => {
+    const n = (seen.get(c.id) || 0) + 1
+    seen.set(c.id, n)
+    return n === 1 ? c : { ...c, id: `${c.id}~${n}` }
+  })
+}
+
+/** Post each result to the system its case came from. Text and file cases have nowhere to go. */
+export async function writeBack(results: CaseResult[], cfg: SourcesConfig, runName: string): Promise<WriteBack[]> {
+  const of = (s: TestCase["source"]) => results.filter((r) => r.case.source === s && r.status !== "stopped")
+  const out: WriteBack[] = []
+  const tasks: [TestCase["source"], (rs: CaseResult[]) => Promise<WriteBack[]>][] = [
+    ["ado", (rs) => adoWriteBack(rs, cfg, runName)],
+    ["jira", (rs) => jiraWriteBack(rs, cfg)],
+    ["xray", (rs) => xrayWriteBack(rs, cfg, runName)],
+    ["testrail", (rs) => testrailWriteBack(rs, cfg, runName)],
+    ["zephyr", (rs) => zephyrWriteBack(rs, cfg, runName)],
+    ["qtest", (rs) => qtestWriteBack(rs, cfg, runName)],
+  ]
+  for (const [source, post] of tasks) {
+    const rs = of(source)
+    if (!rs.length) continue
+    try {
+      out.push(...(await post(rs)))
+    } catch (err) {
+      out.push({ source, text: `${source} results not recorded`, error: (err as Error).message })
+    }
+  }
+  return out
+}