@capagents/forgeqe 0.0.0-stage → 1.0.0

package/src/cases/testrail.ts

@@ -0,0 +1,176 @@
+import { existsSync, readFileSync, statSync } from "node:fs"
+import path from "node:path"
+
+import type { SourcesConfig } from "../config.ts"
+import { basic, envSecret, http } from "./http.ts"
+import { resultText } from "./jira.ts"
+import type { CaseResult, CaseStep, TestCase, WriteBack } from "./types.ts"
+
+type TrCase = {
+  id: number
+  title: string
+  suite_id?: number
+  section_id?: number
+  refs?: string | null
+  custom_preconds?: string | null
+  custom_steps?: string | null
+  custom_expected?: string | null
+  custom_steps_separated?: { content?: string; expected?: string; additional_info?: string }[] | null
+}
+type TrTest = Omit<TrCase, "id"> & { id: number; case_id: number; run_id: number }
+
+export function testrailApi(cfg: SourcesConfig): { base: string; api: string; auth: string; projectId?: number } {
+  const t = cfg.testrail
+  if (!t) throw new Error("TestRail is not set up. Add sources.testrail.url to forgeqe.yaml, or set TESTRAIL_URL.")
+  return { base: t.url, api: `${t.url}/index.php?/api/v2`, auth: basic(envSecret(t.emailEnv, "TestRail"), envSecret(t.tokenEnv, "TestRail")), projectId: t.projectId }
+}
+
+/** Every page of a TestRail list endpoint; handles both the paginated ({ key, _links.next }) and the old array shape. */
+async function list<T>(base: string, first: string, key: string, auth: string): Promise<T[]> {
+  const out: T[] = []
+  let url: string | null = first
+  while (url) {
+    const { data }: { data: unknown } = await http(url, { auth })
+    if (Array.isArray(data)) return [...out, ...(data as T[])]
+    const page = data as Record<string, unknown> & { _links?: { next?: string | null } }
+    out.push(...((page[key] as T[]) || []))
+    const next = page._links?.next
+    url = next ? `${base}/index.php?/${next.replace(/^\/?(index\.php\?)?\/?/, "")}` : null
+  }
+  return out
+}
+
+/** Section names by id, for grouping cases in reports; a section that cannot be read is left out. */
+async function sectionNames(cases: TrCase[], api: string, auth: string): Promise<Map<number, string>> {
+  const names = new Map<number, string>()
+  for (const id of new Set(cases.map((c) => c.section_id).filter((id): id is number => typeof id === "number"))) {
+    try {
+      const { data } = await http<{ name?: string }>(`${api}/get_section/${id}`, { auth })
+      if (data?.name) names.set(id, data.name)
+    } catch {}
+  }
+  return names
+}
+
+function toCase(c: TrCase, base: string, run?: number, testId?: number, sections?: Map<number, string>): TestCase {
+  const separated = (c.custom_steps_separated || []).filter((s) => s.content?.trim())
+  const steps: CaseStep[] = separated.length
+    ? separated.map((s) => ({ action: s.content!.trim(), expected: s.expected?.trim() || undefined, data: s.additional_info?.trim() || undefined }))
+    : c.custom_steps?.trim()
+      ? [{ action: c.custom_steps.trim(), expected: c.custom_expected?.trim() || undefined }]
+      : []
+  return {
+    id: `C${c.id}`,
+    title: c.title,
+    source: "testrail",
+    url: `${base}/index.php?/cases/view/${c.id}`,
+    preconditions: c.custom_preconds?.trim() ? [c.custom_preconds.trim()] : undefined,
+    steps,
+    tags: c.refs ? c.refs.split(",").map((r) => r.trim()).filter(Boolean) : undefined,
+    group: c.section_id !== undefined ? sections?.get(c.section_id) : undefined,
+    requirements: c.refs ? c.refs.split(",").map((r) => r.trim()).filter(Boolean) : undefined,
+    ref: { case: c.id, ...(c.suite_id ? { suite: c.suite_id } : {}), ...(run ? { run } : {}), ...(testId ? { test: testId } : {}), separated: separated.length },
+  }
+}
+
+/** `testrail:C1,C2`, `testrail:run=12` (results go to that run), `testrail:plan=5` (every run in the plan), `testrail:suite=3`. */
+export async function testrailCases(ref: string, cfg: SourcesConfig): Promise<TestCase[]> {
+  const t = testrailApi(cfg)
+  const run = ref.match(/^run=R?(\d+)$/i)?.[1]
+  const plan = ref.match(/^plan=R?(\d+)$/i)?.[1]
+  const suite = ref.match(/^suite=S?(\d+)$/i)?.[1]
+  const runCases = async (runId: number) =>
+    (await list<TrTest>(t.base, `${t.api}/get_tests/${runId}`, "tests", t.auth)).map((test) => toCase({ ...test, id: test.case_id }, t.base, runId, test.id))
+  if (run) return nonEmpty(await runCases(Number(run)), `TestRail run ${run}`)
+  if (plan) {
+    const { data } = await http<{ entries?: { runs?: { id: number }[] }[] }>(`${t.api}/get_plan/${plan}`, { auth: t.auth })
+    const cases: TestCase[] = []
+    for (const e of data?.entries || []) for (const r of e.runs || []) cases.push(...(await runCases(r.id)))
+    return nonEmpty(cases, `TestRail plan ${plan}`)
+  }
+  if (suite) {
+    if (!t.projectId) throw new Error("TestRail suites need sources.testrail.project_id in forgeqe.yaml.")
+    const cases = await list<TrCase>(t.base, `${t.api}/get_cases/${t.projectId}&suite_id=${suite}`, "cases", t.auth)
+    const sections = await sectionNames(cases, t.api, t.auth)
+    return nonEmpty(cases.map((c) => toCase(c, t.base, undefined, undefined, sections)), `TestRail suite ${suite}`)
+  }
+  const ids = ref.split(/[,\s]+/).map((s) => Number(s.replace(/^C/i, ""))).filter((n) => Number.isInteger(n) && n > 0)
+  if (!ids.length) throw new Error(`TestRail reference "${ref}": use testrail:C1,C2, testrail:run=12, testrail:plan=5, or testrail:suite=3.`)
+  const found: TrCase[] = []
+  for (const id of ids) found.push((await http<TrCase>(`${t.api}/get_case/${id}`, { auth: t.auth })).data)
+  const sections = await sectionNames(found, t.api, t.auth)
+  return found.map((c) => toCase(c, t.base, undefined, undefined, sections))
+}
+
+function nonEmpty(cases: TestCase[], what: string): TestCase[] {
+  if (!cases.length) throw new Error(`No test cases in ${what}.`)
+  return cases
+}
+
+const STATUS = { passed: 1, failed: 5, error: 2 } as const
+const STEP_STATUS = { passed: 1, failed: 5, not_run: 3 } as const
+
+function resultFor(r: CaseResult, withSteps: boolean): Record<string, unknown> {
+  const verdicts = new Map((r.stepResults || []).map((v) => [v.step, v]))
+  const out: Record<string, unknown> = {
+    case_id: Number(r.case.ref?.case),
+    status_id: STATUS[r.status as keyof typeof STATUS] ?? 2,
+    comment: resultText(r),
+    elapsed: `${Math.max(1, Math.round(r.ms / 1000))}s`,
+  }
+  if (withSteps && verdicts.size && Number(r.case.ref?.separated)) {
+    out.custom_step_results = r.case.steps.map((s, i) => {
+      const v = verdicts.get(i + 1)
+      return { content: s.action, expected: s.expected || "", actual: v?.actual || "", status_id: v ? STEP_STATUS[v.status] : 3 }
+    })
+  }
+  return out
+}
+
+/** Results go to the run the cases came from; cases read by id get a new run per suite. Screenshots attach to failed results. */
+export async function testrailWriteBack(results: CaseResult[], cfg: SourcesConfig, runName: string): Promise<WriteBack[]> {
+  const t = testrailApi(cfg)
+  const out: WriteBack[] = []
+  const groups = new Map<string, CaseResult[]>()
+  for (const r of results) {
+    const key = r.case.ref?.run ? `run:${r.case.ref.run}` : `suite:${r.case.ref?.suite || ""}`
+    groups.set(key, [...(groups.get(key) || []), r])
+  }
+  for (const [key, list] of groups) {
+    try {
+      let runId = Number(key.startsWith("run:") ? key.slice(4) : 0)
+      let created = false
+      if (!runId) {
+        if (!t.projectId) throw new Error("Recording results for cases read by id needs sources.testrail.project_id, so ForgeQE can create a run.")
+        const suite = key.slice(6)
+        const { data } = await http<{ id: number }>(`${t.api}/add_run/${t.projectId}`, {
+          auth: t.auth,
+          body: { name: runName, include_all: false, case_ids: [...new Set(list.map((r) => Number(r.case.ref?.case)))], ...(suite ? { suite_id: Number(suite) } : {}) },
+        })
+        runId = data.id
+        created = true
+      }
+      const post = (withSteps: boolean) =>
+        http<{ id: number; test_id?: number }[]>(`${t.api}/add_results_for_cases/${runId}`, { auth: t.auth, body: { results: list.map((r) => resultFor(r, withSteps)) } })
+      const { data: posted } = await post(true).catch(() => post(false))
+      let attached = 0
+      for (const [i, r] of list.entries()) {
+        const shot = r.status !== "passed" && r.runDir ? path.join(r.runDir, "failure.png") : ""
+        const resultId = posted?.[i]?.id
+        if (!shot || !resultId || !existsSync(shot) || statSync(shot).size > 8 * 1024 * 1024) continue
+        const form = new FormData()
+        form.append("attachment", new Blob([new Uint8Array(readFileSync(shot))], { type: "image/png" }), "failure.png")
+        const res = await fetch(`${t.api}/add_attachment_to_result/${resultId}`, { method: "POST", headers: { Authorization: t.auth }, body: form })
+        if (res.ok) attached++
+      }
+      out.push({
+        source: "testrail",
+        text: `TestRail run R${runId}${created ? " (new)" : ""}: ${list.length} result${list.length === 1 ? "" : "s"}${attached ? `, ${attached} screenshot${attached === 1 ? "" : "s"}` : ""}`,
+        url: `${t.base}/index.php?/runs/view/${runId}`,
+      })
+    } catch (err) {
+      out.push({ source: "testrail", text: `TestRail ${key.replace(":", " ")}: results not recorded`, error: (err as Error).message })
+    }
+  }
+  return out
+}

package/src/cases/types.ts

@@ -0,0 +1,107 @@
+import type { CodeStatus, StepVerdict, Usage } from "../types.ts"
+import type { Cost } from "../usage.ts"
+import type { Failure } from "./failure.ts"
+
+export type CaseStep = { action: string; data?: string; expected?: string }
+
+export type CaseSource = "text" | "file" | "ado" | "jira" | "xray" | "testrail" | "zephyr" | "qtest"
+
+/** A test case from any source, in one shape. It becomes one browser goal and, once it passes, one test. */
+export type TestCase = {
+  /** Stable id shown everywhere and used to name the test, e.g. "ADO-1234", "SHOP-12", "login.yaml#2". */
+  id: string
+  title: string
+  source: CaseSource
+  /** Link to the item in its system. */
+  url?: string
+  description?: string
+  preconditions?: string[]
+  steps: CaseStep[]
+  /** Page to open first; otherwise browser.start_url, otherwise the agent chooses. */
+  startUrl?: string
+  tags?: string[]
+  /** Where the case lives in its system: area path, section, folder, or component. */
+  group?: string
+  /** Stories or requirements the case covers, e.g. TestRail refs or Jira issues it tests. */
+  requirements?: string[]
+  /** What the source needs to post results back (plan and point ids, issue ids, …). */
+  ref?: Record<string, string | number>
+}
+
+export type CaseStatus = "passed" | "failed" | "stopped" | "error"
+
+export type CaseResult = {
+  case: TestCase
+  status: CaseStatus
+  /** The browser agent's account of the run, or why it could not run. */
+  summary: string
+  startedAt: string
+  finishedAt: string
+  ms: number
+  tokens: number
+  /** The browser agent's tokens, and what they cost at the profile's price. */
+  usage?: Usage
+  cost?: Cost
+  /** Scribe's tokens when it wrote a test for this case, and what they cost. */
+  codeUsage?: Usage
+  codeCost?: Cost
+  runDir?: string
+  finalUrl?: string
+  /** One line per browser step, for reports. */
+  steps?: { text: string; ok: boolean }[]
+  /** The browser agent's verdict on each of the case's numbered steps. */
+  stepResults?: StepVerdict[]
+  /** Set when the coding agent ran for this case. */
+  code?: {
+    status: CodeStatus
+    testFile?: string
+    command?: string
+    attempts: number
+    skills?: string[]
+    handoff?: string
+    error?: string
+    /** The test's full name as its framework reports it. */
+    testName?: string
+    /** The test asserts the correct behaviour of a known defect, marked as an expected failure. */
+    knownDefect?: boolean
+    /** The needs-attention folder the unfinished test was moved to. */
+    attention?: string
+    /** The test the case already had: it passed as it is (no coding job), or the job updated it. */
+    existing?: "reused" | "updated"
+  }
+  /** Why no test was written for this case, when a repo was set and the case did not go to the coding agent. */
+  codeSkipped?: string
+  /** For a case that did not pass: what kind of failure it was, and so what happened next (see src/cases/failure.ts). */
+  failure?: Failure
+  /** The bug filed (or found open) for a functional defect, when bugs are set up. */
+  bug?: { label: string; url?: string }
+  /** The browser run was repeated once because the first one met an environment problem. */
+  retried?: boolean
+}
+
+/** Where a result was recorded, for the suite summary, e.g. "Azure DevOps run 812: https://…". */
+export type WriteBack = {
+  source: CaseSource | "bugs"
+  text: string
+  url?: string
+  error?: string
+  /** Set when the record is about one case (a comment, a bug), so the report can show it with that case. */
+  caseId?: string
+}
+
+const STEP_CAUSE: Record<NonNullable<StepVerdict["cause"]>, string> = { app: "application", test_case: "test case", environment: "environment", automation: "automation" }
+
+/** The case's steps with the agent's verdicts, one line each, for comments and bug reports. */
+export function stepVerdictLines(r: CaseResult): string[] {
+  const verdicts = new Map((r.stepResults || []).map((v) => [v.step, v]))
+  if (!verdicts.size) return []
+  const mark = { passed: "✓", failed: "✗", not_run: "–" } as const
+  return r.case.steps.map((s, i) => {
+    const v = verdicts.get(i + 1)
+    const actual = v?.actual?.trim() ? `: ${v.actual.trim()}` : ""
+    const cause = v?.status === "failed" && v.cause ? ` [${STEP_CAUSE[v.cause]}]` : ""
+    return `${v ? mark[v.status] : "?"} Step ${i + 1} ${v ? v.status.replace("_", " ") : "not reported"}${cause} — ${s.action.trim()}${v && v.status !== "passed" ? actual : ""}`
+  })
+}
+
+export { costOf, type Cost } from "../usage.ts"

package/src/cases/wiki.ts

@@ -0,0 +1,105 @@
+import type { SourcesConfig } from "../config.ts"
+import { adoSettings } from "./ado.ts"
+import { http } from "./http.ts"
+
+const API = "api-version=7.1"
+
+export type WikiPageRequest = {
+  /** Project the wiki is in; sources.azure_devops.project when left out. */
+  project?: string
+  /** Wiki name or id; the project wiki when left out (created when the project has none). */
+  wiki?: string
+  /** Page path such as /Release notes/Sprint 12; missing parent pages are created empty. */
+  path: string
+  /** Markdown. */
+  content: string
+}
+
+export type WikiPageResult = {
+  project: string
+  wiki: string
+  wikiCreated: boolean
+  path: string
+  created: boolean
+  parentsCreated: string[]
+  url: string
+}
+
+type Wiki = { id: string; name: string; type: "projectWiki" | "codeWiki"; versions?: { version: string }[] }
+type Page = { path?: string; remoteUrl?: string }
+
+/**
+ * Creates or updates a wiki page. The project wiki is created first when the project has none, since the Azure DevOps
+ * MCP server can only write pages into a wiki that exists.
+ */
+export async function writeAdoWikiPage(cfg: SourcesConfig, req: WikiPageRequest): Promise<WikiPageResult> {
+  const { auth, org, project: configured } = adoSettings(cfg)
+  const project = (req.project || configured || "").trim()
+  if (!project) throw new Error("Name the Azure DevOps project for the wiki page, or set sources.azure_devops.project.")
+  const path = pagePath(req.path)
+  if (path === "/") throw new Error("The wiki page needs a path such as /Release notes.")
+  const base = `${org}/${encodeURIComponent(project)}`
+
+  const { data } = await http<{ value: Wiki[] }>(`${base}/_apis/wiki/wikis?${API}`, { auth })
+  const wikis = data?.value || []
+  let wiki: Wiki | undefined
+  let wikiCreated = false
+  if (req.wiki?.trim()) {
+    const want = req.wiki.trim().toLowerCase()
+    wiki = wikis.find((w) => w.name.toLowerCase() === want || w.id.toLowerCase() === want)
+    if (!wiki) throw new Error(`No wiki "${req.wiki}" in ${project}. Its wikis: ${wikis.map((w) => w.name).join(", ") || "none"}.`)
+  } else {
+    wiki = wikis.find((w) => w.type === "projectWiki") || (wikis.length === 1 ? wikis[0] : undefined)
+    if (!wiki && wikis.length) throw new Error(`${project} has no project wiki but has code wikis (${wikis.map((w) => w.name).join(", ")}); name one as wiki.`)
+    if (!wiki) {
+      const { data: p } = await http<{ id: string }>(`${org}/_apis/projects/${encodeURIComponent(project)}?${API}`, { auth })
+      wiki = (await http<Wiki>(`${base}/_apis/wiki/wikis?${API}`, { auth, body: { name: `${project}.wiki`, projectId: p.id, type: "projectWiki" } })).data
+      wikiCreated = true
+    }
+  }
+
+  const branch = wiki.type === "codeWiki" && wiki.versions?.[0]?.version
+  const pages = `${base}/_apis/wiki/wikis/${encodeURIComponent(wiki.id)}/pages`
+  const at = (p: string) =>
+    `${pages}?path=${encodeURIComponent(p)}&${API}${branch ? `&versionDescriptor.version=${encodeURIComponent(branch)}&versionDescriptor.versionType=branch` : ""}`
+  const etag = async (p: string): Promise<string | null> => {
+    try {
+      const { headers } = await http(at(p), { auth })
+      return headers.get("etag") || ""
+    } catch (err) {
+      if (/failed: 404\b/.test((err as Error).message)) return null
+      throw err
+    }
+  }
+
+  const parentsCreated: string[] = []
+  const parts = path.split("/").filter(Boolean)
+  for (let i = 1; i < parts.length; i++) {
+    const parent = `/${parts.slice(0, i).join("/")}`
+    if ((await etag(parent)) !== null) continue
+    await http(at(parent), { auth, method: "PUT", body: { content: "" } })
+    parentsCreated.push(parent)
+  }
+
+  const existing = await etag(path)
+  const { data: page } = await http<Page>(at(path), {
+    auth,
+    method: "PUT",
+    body: { content: req.content },
+    ...(existing ? { headers: { "If-Match": existing } } : {}),
+  })
+  return {
+    project,
+    wiki: wiki.name,
+    wikiCreated,
+    path,
+    created: existing === null,
+    parentsCreated,
+    url: page?.remoteUrl || `${base}/_wiki/wikis/${encodeURIComponent(wiki.name)}?pagePath=${encodeURIComponent(path)}`,
+  }
+}
+
+function pagePath(raw: string): string {
+  const parts = String(raw || "").split("/").map((s) => s.trim()).filter(Boolean)
+  return `/${parts.join("/")}`
+}

package/src/cases/xray.ts

@@ -0,0 +1,206 @@
+import { existsSync, readFileSync, statSync } from "node:fs"
+import path from "node:path"
+
+import type { SourcesConfig } from "../config.ts"
+import { adfToText, envSecret, http } from "./http.ts"
+import { jiraApi, jiraIssues, resultText } from "./jira.ts"
+import type { CaseResult, CaseStep, TestCase, WriteBack } from "./types.ts"
+
+const TEST_FIELDS = `issueId testType { name kind } steps { action data result } gherkin unstructured
+  preconditions(limit: 10) { results { definition jira(fields: ["key", "summary"]) } }
+  jira(fields: ["key", "summary", "description", "labels"])`
+
+type CloudTest = {
+  issueId: string
+  testType?: { name?: string; kind?: string }
+  steps?: { action?: string; data?: string; result?: string }[]
+  gherkin?: string
+  unstructured?: string
+  preconditions?: { results?: { definition?: string; jira?: { key?: string; summary?: string } }[] }
+  jira: { key: string; summary?: string; description?: unknown; labels?: string[] }
+}
+
+const server = (cfg: SourcesConfig) => Boolean(cfg.jira && !cfg.jira.cloud)
+
+export async function xrayCloudToken(cfg: SourcesConfig): Promise<string> {
+  const { data } = await http<string>(`${cfg.xray.url}/api/v2/authenticate`, {
+    auth: "",
+    body: { client_id: envSecret(cfg.xray.clientIdEnv, "Xray Cloud"), client_secret: envSecret(cfg.xray.clientSecretEnv, "Xray Cloud") },
+  })
+  return `Bearer ${String(data).replace(/^"|"$/g, "")}`
+}
+
+export async function xrayGraphql<T>(cfg: SourcesConfig, auth: string, query: string, variables: Record<string, unknown>): Promise<T> {
+  const { data } = await http<{ data?: T; errors?: { message: string }[] }>(`${cfg.xray.url}/api/v2/graphql`, { auth, body: { query, variables } })
+  if (data?.errors?.length) throw new Error(`Xray: ${data.errors.map((e) => e.message).join("; ")}`)
+  return data!.data as T
+}
+
+/** `xray:SHOP-1,SHOP-2`, `xray:jql=<query>`, or `xray:plan=SHOP-100` (the plan's tests; results link to the plan). */
+export async function xrayCases(ref: string, cfg: SourcesConfig): Promise<TestCase[]> {
+  const plan = ref.match(/^plan=([A-Z][A-Z0-9_]*-\d+)$/i)?.[1]?.toUpperCase()
+  const jql = ref.match(/^jql=(.+)$/s)?.[1]
+  const keys = !plan && !jql ? ref.split(/[,\s]+/).map((k) => k.trim().toUpperCase()).filter(Boolean) : []
+  if (!plan && !jql && !keys.length) throw new Error(`Xray reference "${ref}": use xray:SHOP-1,SHOP-2, xray:jql=<query>, or xray:plan=SHOP-100.`)
+  const cases = server(cfg) ? await serverCases({ plan, jql, keys }, cfg) : await cloudCases({ plan, jql, keys }, cfg)
+  if (!cases.length) throw new Error(`No Xray tests for "${ref}".`)
+  return plan ? cases.map((c) => ({ ...c, ref: { ...c.ref, plan } })) : cases
+}
+
+async function cloudCases(sel: { plan?: string; jql?: string; keys: string[] }, cfg: SourcesConfig): Promise<TestCase[]> {
+  const auth = await xrayCloudToken(cfg)
+  const tests: CloudTest[] = []
+  for (let start = 0; ; start += 100) {
+    let page: { total: number; results: CloudTest[] }
+    if (sel.plan) {
+      const data = await xrayGraphql<{ getTestPlans: { results: { tests: { total: number; results: CloudTest[] } }[] } }>(
+        cfg,
+        auth,
+        `query($jql: String, $start: Int) { getTestPlans(jql: $jql, limit: 1) { results { tests(limit: 100, start: $start) { total results { ${TEST_FIELDS} } } } } }`,
+        { jql: `key = ${sel.plan}`, start },
+      )
+      const found = data.getTestPlans.results[0]
+      if (!found) throw new Error(`Xray test plan ${sel.plan} not found.`)
+      page = found.tests
+    } else {
+      const jql = sel.jql || `key in (${sel.keys.join(",")})`
+      const data = await xrayGraphql<{ getTests: { total: number; results: CloudTest[] } }>(
+        cfg,
+        auth,
+        `query($jql: String, $start: Int) { getTests(jql: $jql, limit: 100, start: $start) { total results { ${TEST_FIELDS} } } }`,
+        { jql, start },
+      )
+      page = data.getTests
+    }
+    tests.push(...page.results)
+    if (!page.results.length || tests.length >= page.total) break
+  }
+  const browse = cfg.jira ? `${cfg.jira.url}/browse/` : undefined
+  return tests.map((t) => {
+    const steps: CaseStep[] = (t.steps || [])
+      .filter((s) => s.action?.trim())
+      .map((s) => ({ action: s.action!.trim(), data: s.data?.trim() || undefined, expected: s.result?.trim() || undefined }))
+    const body = [adfToText(t.jira.description), t.gherkin?.trim() ? `Scenario:\n${t.gherkin.trim()}` : "", t.unstructured?.trim() || ""]
+    const pre = (t.preconditions?.results || []).map((p) => [p.jira?.summary, p.definition].filter(Boolean).join(": ")).filter(Boolean)
+    return {
+      id: t.jira.key,
+      title: t.jira.summary || t.jira.key,
+      source: "xray" as const,
+      url: browse ? browse + t.jira.key : undefined,
+      description: body.filter(Boolean).join("\n\n") || undefined,
+      preconditions: pre.length ? pre : undefined,
+      steps,
+      tags: t.jira.labels?.length ? t.jira.labels : undefined,
+      ref: { test: t.jira.key },
+    }
+  })
+}
+
+type ServerTest = {
+  key: string
+  type?: string
+  definition?: string
+  steps?: { step?: { raw?: string }; data?: { raw?: string }; result?: { raw?: string } }[]
+}
+
+async function serverCases(sel: { plan?: string; jql?: string; keys: string[] }, cfg: SourcesConfig): Promise<TestCase[]> {
+  const j = jiraApi(cfg, "Xray Server")
+  const q = sel.keys.length ? `keys=${sel.keys.join(";")}` : `jql=${encodeURIComponent(sel.plan ? `issue in testPlanTests("${sel.plan}")` : sel.jql!)}`
+  const { data } = await http<ServerTest[]>(`${j.url}/rest/raven/1.0/api/test?${q}`, { auth: j.auth })
+  const tests = data || []
+  if (!tests.length) return []
+  const issues = new Map((await jiraIssues(tests.map((t) => t.key).join(","), j)).map((i) => [i.key, i]))
+  return tests.map((t) => {
+    const issue = issues.get(t.key)
+    const steps: CaseStep[] = (t.steps || [])
+      .filter((s) => s.step?.raw?.trim())
+      .map((s) => ({ action: s.step!.raw!.trim(), data: s.data?.raw?.trim() || undefined, expected: s.result?.raw?.trim() || undefined }))
+    const body = [adfToText(issue?.fields.description), !steps.length && t.definition?.trim() ? t.definition.trim() : ""]
+    return {
+      id: t.key,
+      title: issue?.fields.summary || t.key,
+      source: "xray" as const,
+      url: `${j.url}/browse/${t.key}`,
+      description: body.filter(Boolean).join("\n\n") || undefined,
+      steps,
+      tags: issue?.fields.labels?.length ? issue.fields.labels : undefined,
+      ref: { test: t.key },
+    }
+  })
+}
+
+const MAX_EVIDENCE = 4 * 1024 * 1024
+
+function evidence(r: CaseResult): { data: string; filename: string; contentType: string }[] {
+  if (!r.runDir) return []
+  const out = []
+  for (const [name, type] of [["failure.png", "image/png"]] as const) {
+    const file = path.join(r.runDir, name)
+    if (existsSync(file) && statSync(file).size <= MAX_EVIDENCE) {
+      out.push({ data: readFileSync(file).toString("base64"), filename: name, contentType: type })
+    }
+  }
+  return out
+}
+
+/** One Test Execution per test plan (and one for tests without a plan), with each test's status and comment. */
+export async function xrayWriteBack(results: CaseResult[], cfg: SourcesConfig, runName: string): Promise<WriteBack[]> {
+  const isServer = server(cfg)
+  const status = (s: CaseResult["status"]) => (s === "passed" ? (isServer ? "PASS" : "PASSED") : s === "failed" ? (isServer ? "FAIL" : "FAILED") : "TODO")
+  const groups = new Map<string, CaseResult[]>()
+  for (const r of results) {
+    const plan = String(r.case.ref?.plan || "")
+    groups.set(plan, [...(groups.get(plan) || []), r])
+  }
+  const out: WriteBack[] = []
+  const auth = isServer ? jiraApi(cfg, "Xray Server").auth : await xrayCloudToken(cfg)
+  const url = isServer ? `${cfg.jira!.url}/rest/raven/1.0/import/execution` : `${cfg.xray.url}/api/v2/import/execution`
+  for (const [plan, list] of groups) {
+    const body = {
+      info: {
+        summary: runName,
+        description: `Run by ForgeQE: ${list.filter((r) => r.status === "passed").length}/${list.length} passed.`,
+        startDate: list.map((r) => r.startedAt).sort()[0],
+        finishDate: list.map((r) => r.finishedAt).sort().at(-1),
+        ...(plan ? { testPlanKey: plan } : {}),
+      },
+      tests: list.map((r) => {
+        const files = evidence(r)
+        const verdicts = new Map((r.stepResults || []).map((v) => [v.step, v]))
+        const stepStatus = { passed: status("passed"), failed: status("failed"), not_run: "TODO" } as const
+        const steps =
+          verdicts.size && r.case.steps.length
+            ? r.case.steps.map((_, i) => {
+                const v = verdicts.get(i + 1)
+                return { status: v ? stepStatus[v.status] : "TODO", ...(v?.actual ? { actualResult: v.actual.slice(0, 2000) } : {}) }
+              })
+            : undefined
+        return {
+          testKey: String(r.case.ref?.test || r.case.id),
+          start: r.startedAt,
+          finish: r.finishedAt,
+          status: status(r.status),
+          comment: resultText(r).slice(0, 4000),
+          ...(steps ? { steps } : {}),
+          ...(files.length ? { [isServer ? "evidences" : "evidence"]: files } : {}),
+        }
+      }),
+    }
+    try {
+      type Imported = { key?: string; self?: string; testExecIssue?: { key?: string } }
+      const withoutSteps = { ...body, tests: body.tests.map(({ steps: _steps, ...t }) => t) }
+      const { data } = await http<Imported>(url, { auth, body }).catch((err) =>
+        body.tests.some((t) => t.steps) ? http<Imported>(url, { auth, body: withoutSteps }) : Promise.reject(err),
+      )
+      const key = data?.key || data?.testExecIssue?.key
+      out.push({
+        source: "xray",
+        text: `Xray Test Execution ${key || "created"}${plan ? ` for ${plan}` : ""} (${list.length} tests)`,
+        url: key && cfg.jira ? `${cfg.jira.url}/browse/${key}` : undefined,
+      })
+    } catch (err) {
+      out.push({ source: "xray", text: `Xray results${plan ? ` for ${plan}` : ""} not imported`, error: (err as Error).message })
+    }
+  }
+  return out
+}