enhancement(import): link JUnit/CLI results to existing cases by ID (#394)

* enhancement(import): link JUnit/CLI results to existing cases by ID

Adds opt-in case-ID matching to the test-results importer so renaming an
automated test no longer creates a duplicate case. A result can declare the
existing case it belongs to via an ID in the test name (presets: brackets
[123], C123, TC-123) or a test_id / testplanit_case_id JUnit property. When
present, the result links to that case (scoped to the project) and skips
name+className matching; multiple IDs link to multiple cases. Unknown IDs are
skipped and surfaced as warnings rather than creating duplicates.

Configured via the CLI --case-matcher / --case-id-format flags; default off,
so existing imports are unchanged. Matching uses a fixed set of compiled
presets only, so no caller-supplied regex runs server-side.

* docs(import-export): enhance CSV and test results import instructions

Updated the import-export documentation to clarify the process for importing test cases and results. Added details on using the Import button and drag-and-drop functionality, and improved formatting examples for test steps to include code blocks with the `text` language specified. This enhances readability and user understanding of the import features.

* chore(workspace): add iframe-resizer to allowed builds

Updated the pnpm workspace configuration to include 'iframe-resizer' in the list of allowed builds, enhancing the build process for the project.

Author: therealbrad

cli/README.md

@@ -7,7 +7,7 @@ Command-line interface for TestPlanIt - import test results and manage test data
 The CLI supports importing test results from 7 different formats:
 
 | Format | Description | File Extensions |
-|--------|-------------|-----------------|
+| -------- | ------------- | ----------------- |
 | `junit` | JUnit XML | `.xml` |
 | `testng` | TestNG XML | `.xml` |
 | `xunit` | xUnit XML | `.xml` |
@@ -25,7 +25,7 @@ The CLI can auto-detect the format based on file content, or you can specify it
 Download the appropriate binary for your platform from the [CLI releases](https://github.com/testplanit/testplanit/releases?q=cli&expanded=true):
 
 | Platform | Binary |
-|----------|--------|
+| ---------- | -------- |
 | Linux (x64) | `testplanit-linux-x64` |
 | macOS (Apple Silicon) | `testplanit-macos-arm64` |
 | macOS (Intel) | `testplanit-macos-x64` |
@@ -97,9 +97,13 @@ testplanit import <files...> --project <id|name> --name <name> [options]
 - `-f, --folder <value>` - Parent folder for test cases (ID or exact name)
 - `-t, --tags <values>` - Tags (comma-separated IDs or names; use quotes for names with commas)
 - `-r, --test-run <value>` - Existing test run to append results (ID or exact name)
+- `--case-matcher <mode>` - Link results to existing cases by ID: `off`, `name`, `property`, `auto` (default: `off`)
+- `--case-id-format <preset>` - Case-ID pattern in the test name when matching by name: `brackets`, `c`, `tc` (default: `brackets`)
 
 **Note:** For project, state, config, milestone, folder, and test run options, the CLI looks up entities by exact name match. If no match is found, an error is returned. For tags, if a tag name doesn't exist, it will be created automatically.
 
+**Linking results to existing cases by ID:** By default a result is matched to a case by name and class name, so renaming a test creates a duplicate. With `--case-matcher`, a result instead links to an existing case by an ID in the test name (`--case-id-format`: `brackets` → `[123]`, `c` → `C123`, `tc` → `TC-123`) or a `test_id` / `testplanit_case_id` JUnit `<property>` (`property`/`auto`). Multiple IDs link one result to multiple cases; an ID not found in the project is skipped with a warning.
+
 **Examples:**
 
 ```bash
@@ -121,6 +125,12 @@ testplanit import cucumber-report.json -p 1 -n "BDD Tests" -F cucumber
 # Import multiple files with glob pattern
 testplanit import "./test-results/*.xml" -p 1 -n "CI Build"
 
+# Link results to existing cases by an ID in the test name (e.g. "[123] login")
+testplanit import results.xml -p 1 -n "Build 123" --case-matcher name
+
+# Link by a test_id property in the XML, falling back to the name pattern
+testplanit import results.xml -p 1 -n "Build 123" --case-matcher auto
+
 # Import with IDs
 testplanit import results.xml \
   --project 1 \

cli/src/commands/import.ts

@@ -18,7 +18,16 @@ import {
   formatFileSize,
   resolveTestRunAttachmentFiles,
 } from "../lib/attachments.js";
-import { TEST_RESULT_FORMATS, type TestResultFormat, type SSEProgressEvent, type ImportOptions } from "../types.js";
+import {
+  TEST_RESULT_FORMATS,
+  CASE_MATCHERS,
+  CASE_ID_FORMATS,
+  type TestResultFormat,
+  type SSEProgressEvent,
+  type ImportOptions,
+  type CaseMatcher,
+  type CaseIdFormat,
+} from "../types.js";
 
 const VALID_FORMATS = ["auto", ...Object.keys(TEST_RESULT_FORMATS)] as const;
 
@@ -42,6 +51,16 @@ export function createImportCommand(): Command {
     .option("-d, --attachments-dir <path>", "Base directory for resolving attachment paths (default: directory of test result file)")
     .option("--no-attachments", "Skip uploading attachments")
     .option("-a, --run-attachments <files...>", "Files to attach to the test run (e.g., test plans, reports)")
+    .option(
+      "--case-matcher <mode>",
+      `Link results to existing cases by ID: ${CASE_MATCHERS.join(", ")} (default: off)`,
+      "off"
+    )
+    .option(
+      "--case-id-format <preset>",
+      `Case-ID pattern in the test name when matching by name: ${CASE_ID_FORMATS.join(", ")} (default: brackets, e.g. [123])`,
+      "brackets"
+    )
     .addHelpText("after", `
 Examples:
 
@@ -82,6 +101,15 @@ Examples:
   Import without uploading attachments:
     $ testplanit import ./results.xml -p "My Project" -n "Build" --no-attachments
 
+  Link results to existing cases by an ID in the test name (e.g. "[123] login"):
+    $ testplanit import ./results.xml -p "My Project" -n "Build" --case-matcher name
+
+  Link by a test_id property in the XML, falling back to the name pattern:
+    $ testplanit import ./results.xml -p "My Project" -n "Build" --case-matcher auto
+
+  Use the TestRail-style C-prefix pattern (e.g. "C123 login"):
+    $ testplanit import ./results.xml -p "My Project" -n "Build" --case-matcher name --case-id-format c
+
   Attach files to the test run (test plans, reports, etc.):
     $ testplanit import ./results.xml -p "My Project" -n "Build" -a ./test-plan.pdf ./coverage-report.html
 `)
@@ -108,6 +136,20 @@ Examples:
         process.exit(1);
       }
 
+      // Validate case-ID matching options
+      const caseMatcher = options.caseMatcher.toLowerCase() as CaseMatcher;
+      if (!CASE_MATCHERS.includes(caseMatcher)) {
+        logger.error(`Invalid case matcher: ${options.caseMatcher}`);
+        logger.info(`Valid matchers: ${CASE_MATCHERS.join(", ")}`);
+        process.exit(1);
+      }
+      const caseIdFormat = options.caseIdFormat.toLowerCase() as CaseIdFormat;
+      if (!CASE_ID_FORMATS.includes(caseIdFormat)) {
+        logger.error(`Invalid case ID format: ${options.caseIdFormat}`);
+        logger.info(`Valid formats: ${CASE_ID_FORMATS.join(", ")}`);
+        process.exit(1);
+      }
+
       // Expand file patterns using glob
       const files: string[] = [];
       for (const pattern of filePatterns) {
@@ -171,6 +213,12 @@ Examples:
           format: format,
         };
 
+        // Only send case-ID matching config when enabled
+        if (caseMatcher !== "off") {
+          importOptions.caseMatcher = caseMatcher;
+          importOptions.caseIdFormat = caseIdFormat;
+        }
+
         // Resolve state
         if (options.state) {
           logger.updateSpinner("Resolving workflow state...");
@@ -227,6 +275,20 @@ Examples:
         console.log();
         logger.success(`Test run created with ID: ${logger.formatNumber(result.testRunId)}`);
 
+        // Surface any results that referenced an unknown case ID (skipped)
+        if (result.caseIdWarnings && result.caseIdWarnings.length > 0) {
+          console.log();
+          logger.warn(
+            `Skipped ${logger.formatNumber(result.caseIdWarnings.length)} result(s) referencing a case ID not found in this project:`
+          );
+          for (const warning of result.caseIdWarnings.slice(0, 10)) {
+            logger.dim(`    - C${warning.requestedCaseId} (${warning.testName})`);
+          }
+          if (result.caseIdWarnings.length > 10) {
+            logger.dim(`    ... and ${result.caseIdWarnings.length - 10} more`);
+          }
+        }
+
         // Handle attachment uploads if present and not disabled
         if (
           options.attachments !== false &&

cli/src/lib/api.ts

@@ -143,6 +143,14 @@ export async function importTestResults(
     }
   }
 
+  if (options.caseMatcher) {
+    form.append("caseMatcher", options.caseMatcher);
+  }
+
+  if (options.caseIdFormat) {
+    form.append("caseIdFormat", options.caseIdFormat);
+  }
+
   // Add files (read as buffers for compatibility with form.getBuffer())
   for (const filePath of files) {
     const absolutePath = path.resolve(filePath);
@@ -224,6 +232,7 @@ export async function importTestResults(
             result = {
               testRunId: data.testRunId,
               attachmentMappings: data.attachmentMappings,
+              caseIdWarnings: data.caseIdWarnings,
             };
           }
         } catch (e) {

cli/src/types.ts

@@ -30,6 +30,26 @@ export const TEST_RESULT_FORMATS: Record<Exclude<TestResultFormat, "auto">, { la
   cucumber: { label: "Cucumber JSON", extensions: [".json"] },
 };
 
+/**
+ * Case-ID matching: how (and whether) to link results to existing cases by an
+ * ID parsed from the test name or a `test_id` property, instead of matching on
+ * name + class name.
+ */
+export type CaseMatcher = "off" | "name" | "property" | "auto";
+export type CaseIdFormat = "brackets" | "c" | "tc";
+
+export const CASE_MATCHERS: readonly CaseMatcher[] = [
+  "off",
+  "name",
+  "property",
+  "auto",
+];
+export const CASE_ID_FORMATS: readonly CaseIdFormat[] = [
+  "brackets",
+  "c",
+  "tc",
+];
+
 /**
  * Import options - IDs are resolved before being passed to the API
  */
@@ -43,6 +63,8 @@ export interface ImportOptions {
   parentFolderId?: number;
   tagIds?: number[];
   testRunId?: number;
+  caseMatcher?: CaseMatcher;
+  caseIdFormat?: CaseIdFormat;
 }
 
 /**
@@ -104,10 +126,21 @@ export interface AttachmentMapping {
 }
 
 /**
- * Extended SSE progress event with attachment mappings
+ * A test whose declared case ID could not be linked (unknown id, or not in
+ * the target project). The result for this test was skipped.
+ */
+export interface CaseIdWarning {
+  testName: string;
+  className: string | null;
+  requestedCaseId: number;
+}
+
+/**
+ * Extended SSE progress event with attachment mappings and advisory warnings
  */
 export interface ImportSSEProgressEvent extends SSEProgressEvent {
   attachmentMappings?: AttachmentMapping[];
+  caseIdWarnings?: CaseIdWarning[];
 }
 
 /**
@@ -154,11 +187,12 @@ export interface BulkAttachmentUploadResponse {
 }
 
 /**
- * Import result with optional attachment mappings
+ * Import result with optional attachment mappings and advisory warnings
  */
 export interface ImportResult {
   testRunId: number;
   attachmentMappings?: AttachmentMapping[];
+  caseIdWarnings?: CaseIdWarning[];
 }
 
 /**

docs/docs/cli.md

@@ -144,6 +144,8 @@ testplanit import <files...> --project <id|name> --name <name> [options]
 | `-d, --attachments-dir <path>` | Base directory for resolving attachment paths (default: directory of test result file) |
 | `--no-attachments` | Skip uploading attachments from test results |
 | `-a, --run-attachments <files...>` | Files to attach to the test run (e.g., test plans, reports) |
+| `--case-matcher <mode>` | Link results to existing cases by ID: `off`, `name`, `property`, `auto` (default: `off`) |
+| `--case-id-format <preset>` | Case-ID pattern in the test name when matching by name: `brackets`, `c`, `tc` (default: `brackets`) |
 
 :::note
 For project, state, config, milestone, folder, and test run options, the CLI looks up entities by exact name match. If no match is found, an error is returned. For tags, if a tag name doesn't exist, it will be created automatically.
@@ -171,6 +173,42 @@ Use `-d, --attachments-dir` to specify a custom base directory for resolving rel
 
 Use `--no-attachments` to skip uploading test result attachments entirely.
 
+#### Linking results to existing cases by ID
+
+By default the importer matches each result to a case by **name and class name**. If your automation renames a test, the importer no longer recognizes it and creates a duplicate case. To prevent this, assign each automated test the ID of the case it belongs to, and turn on case-ID matching with `--case-matcher`. When a result carries a recognized ID, it links to that case **regardless of the test name**, so renames stop creating duplicates.
+
+There are two ways to carry the ID, controlled by `--case-matcher`:
+
+- **`name`** — the ID is embedded in the test name; the pattern is chosen with `--case-id-format` (see below).
+- **`property`** — the ID is carried in a JUnit `<property>` named `test_id` (or `testplanit_case_id`), following the convention used by TestRail and Xray (see below).
+- **`auto`** — try the `test_id` property first, then fall back to the name pattern.
+
+Name patterns (`--case-id-format`):
+
+| Preset | Matches | Example test name |
+| -------- | --------- | ------------------- |
+| `brackets` (default) | `[123]`, `[C123]`, `[123, 456]` | `[123] user can log in` |
+| `c` | `C123` | `C123 user can log in` |
+| `tc` | `TC-123`, `TC123` | `TC-123 user can log in` |
+
+Property form (`--case-matcher property` or `auto`):
+
+```xml
+<testcase name="user can log in" classname="auth.LoginTests">
+  <properties>
+    <property name="test_id" value="123"/>
+  </properties>
+</testcase>
+```
+
+Notes:
+
+- A single test may reference multiple cases (`[123, 456]` or `value="123,456"`); each referenced case receives the same result.
+- Tests **without** an ID still import normally — they are matched/created by name and class name as before.
+- If a referenced case ID does not exist in the target project, that result is **skipped** (never auto-created under a wrong name) and reported as a warning at the end of the import.
+- The ID is the numeric TestPlanIt case ID; a leading `C` or `#` is tolerated.
+- Property matching requires a reporter that writes per-`<testcase>` properties (e.g. pytest's `record_property`, the Playwright JUnit reporter with `embedAnnotationsAsProperties`, NUnit `[Property]`). Frameworks that only emit suite-level properties (e.g. Maven Surefire) should use the name-based pattern instead.
+
 #### Examples
 
 ```bash
@@ -192,6 +230,15 @@ testplanit import cucumber-report.json -p 1 -n "BDD Tests" -F cucumber
 # Import multiple files with glob pattern
 testplanit import "./test-results/*.xml" -p 1 -n "CI Build"
 
+# Link results to existing cases by an ID in the test name (e.g. "[123] login")
+testplanit import results.xml -p 1 -n "Build 123" --case-matcher name
+
+# Use the TestRail-style C-prefix pattern (e.g. "C123 login")
+testplanit import results.xml -p 1 -n "Build 123" --case-matcher name --case-id-format c
+
+# Link by a test_id property in the XML, falling back to the name pattern
+testplanit import results.xml -p 1 -n "Build 123" --case-matcher auto
+
 # Import with IDs
 testplanit import results.xml \
   --project 1 \

docs/docs/import-export.md

@@ -30,10 +30,12 @@ Import test cases from CSV files with flexible field mapping.
 There are two ways to start a CSV import:
 
 **Using the Import button:**
+
 1. Navigate to **Repository** in your project
 2. Click the **Import** button in the toolbar
 
 **Using drag and drop:**
+
 1. Drag a `.csv` file from your desktop over the Repository page
 2. A full-page drop overlay will appear indicating you can drop to import
 3. Drop the file — the import wizard opens automatically with your file pre-loaded
@@ -104,15 +106,15 @@ Test steps in a single cell can be formatted in several ways:
 
 **Simple Format:**
 
-```
+```text
 1. Step one
 2. Step two
 3. Step three
 ```
 
 **Detailed Format with Expected Results** — separate the step from its expected result with a pipe (`|`):
 
-```
+```text
 1. Navigate to login page | Login page displays
 2. Enter username and password | Fields accept input
 3. Click login button | User is redirected to dashboard
@@ -122,7 +124,7 @@ Test steps in a single cell can be formatted in several ways:
 
 Steps can also contain markdown formatting:
 
-```
+```text
 1. Navigate to the **Login** page | Login page displays with _username_ and _password_ fields
 2. Enter `admin` credentials | Fields accept input
 3. Click **Submit** | User is redirected to [Dashboard](/dashboard)
@@ -297,11 +299,13 @@ TestPlanIt supports importing test results from the following formats:
 There are two ways to start a test results import:
 
 **Using the Import button:**
+
 1. Navigate to **Test Runs** in your project
 2. Click **Import Results** button
 3. The import dialog opens with format options
 
 **Using drag and drop:**
+
 1. Drag one or more test result files (`.xml`, `.trx`, or `.json`) from your desktop over the Test Runs page
 2. A full-page drop overlay will appear indicating you can drop to import
 3. Drop the files — the import dialog opens automatically with your files pre-loaded
@@ -758,6 +762,8 @@ parentFolderId: 101
 configId: 102 (optional)
 milestoneId: 103 (optional)
 tagIds: [1, 2, 3] (optional)
+caseMatcher: "off" | "name" | "property" | "auto" (optional, default "off")
+caseIdFormat: "brackets" | "c" | "tc" (optional, default "brackets")
 ```
 
 Response is Server-Sent Events (SSE) with progress updates:
@@ -768,6 +774,8 @@ Response is Server-Sent Events (SSE) with progress updates:
 {"complete": true, "testRunId": 12345}
 ```
 
+By default each result is matched to a case by **name + class name**, so renaming an automated test creates a duplicate case. Set `caseMatcher` to instead link results to an existing case by an ID carried in the test name (`caseIdFormat` preset) or a `test_id` / `testplanit_case_id` JUnit property — see [Linking results to existing cases by ID](./cli.md#linking-results-to-existing-cases-by-id) in the CLI guide for the full behavior. Results whose referenced case ID is not found in the project are skipped and listed in the final SSE event as `caseIdWarnings`.
+
 ### Export
 
 There is no server-side export endpoint. CSV, PDF, and other exports are generated in the browser from data already loaded by the Repository view — the export reflects the current filter, scope, and column selection in the UI. Use the **Export** button in the Repository toolbar to configure and download.

pnpm-workspace.yaml

@@ -25,6 +25,7 @@ allowBuilds:
   'core-js': true
   'core-js-pure': true
   'esbuild': true
+  iframe-resizer: true
   'keytar': true
   'msgpackr-extract': true
   'msw': true