Test Case Import Formats

This document defines the canonical CSV and JSON formats that Codmir accepts when importing test cases into the Library. Use these instructions to convert spreadsheets and other sources into the expected structure.

Rules

• Title is required for every test case.
• Priority is one of: Low, Medium, High (case-insensitive; L/M/H also accepted and normalized).
• Choose one of two templates per case:
  • steps: structured steps with action/expected pairs
  • text: free-form step text
• Optional fields: estimate (e.g., 5m, 1h), preconditions.

CSV format

Two CSV styles are supported.

1) Steps style (preferred)

• Column headers:
  • Required: title
  • Optional: priority, estimate, preconditions
  • Steps: repeated pairs step N action, step N expected for N = 1..N

title,priority,estimate,preconditions,step 1 action,step 1 expected,step 2 action,step 2 expected
Login works,High,5m,User exists,Open login page,Page visible,Enter credentials,Dashboard is loaded

Notes:

• Column names are case-insensitive; extra spaces are ignored (e.g., "Step 1 Action").
• Missing "expected" is allowed; it becomes an empty string.

2) Text style

• Column headers:
  • Required: title
  • Optional: priority, estimate, preconditions
  • Required for this style: stepsText

title,priority,estimate,preconditions,stepsText
End-to-end happy path,Medium,15m,,1) Open app\n2) Login\n3) Verify dashboard

JSON format

Provide either an array of cases or an object with a cases array.

{
  "cases": [
    {
      "title": "Login works",
      "priority": "High",
      "template": "steps",
      "estimate": "5m",
      "preconditions": "User exists",
      "steps": [
        { "action": "Open login page", "expected": "Page visible" },
        { "action": "Enter credentials", "expected": "Dashboard is loaded" }
      ]
    },
    {
      "title": "Happy path",
      "priority": "Medium",
      "template": "text",
      "stepsText": "1) Open app\n2) Login\n3) Verify dashboard"
    }
  ]
}

Schema summary:

{
  "title": "string (required)",
  "priority": "Low | Medium | High (optional; defaults to Medium)",
  "template": "steps | text (optional; defaults to steps)",
  "estimate": "string (optional)",
  "preconditions": "string (optional)",
  "steps": [{ "action": "string", "expected": "string" }],
  "stepsText": "string"
}

Normalization and validation

• Priority normalization: values starting with H → High, L → Low, else Medium.
• Empty or missing step fields are allowed; they are trimmed to empty strings.
• Each case must have a non-empty title after trimming.

Legacy CSV mapping (example_test_cases.csv)

When importing spreadsheets shaped like public/example_test_cases.csv, Codmir applies this mapping automatically:

• Test Case Title → title
• Steps (multi-line cell) → split into ordered steps; each line becomes a step action
• Expected Result → attached as expected to the last step (or becomes a single expected-only step if no steps were detected)
• Actual Result, Status, and the extra Column 7..10 → ignored during import
• ID → not used for numbering; Codmir assigns a project-scoped sequential ID (TC-<number>). If you need the legacy ID preserved, add it to the JSON payload as a custom field (e.g., sourceId)—contact us to enable storing it in the steps JSON blob.

Status handling:

• Status is not imported; Codmir defaults to "Not Started" for all imported cases.

Priority handling:

• If no priority column is present, Codmir defaults to "Medium".

Tip:

• If you need to preserve the original status or priority, consider adding custom fields to your JSON payload.

Conversion guidance for AI agents

When given arbitrary spreadsheets or documents, convert to the formats above using the following approach:

• Detect template per case
  • If you can reliably extract action/expected pairs, use template = "steps" and emit steps array in order.
  • Otherwise, concatenate visible step text into stepsText and use template = "text".
• Map columns
  • Title → title
  • Priority → normalize to Low/Medium/High
  • Estimate → copy as-is (keep units if present)
  • Preconditions/Setup → preconditions
  • Steps →
    • If columns like Step 1, Expected 1, Step 2, Expected 2 exist, map to steps items { action, expected }.
    • If only a single step narrative field exists, map to stepsText.
• Trim and sanitize
  • Remove leading/trailing whitespace; convert multi-line cells to \n where needed.
• Validate
  • Ensure every case has title and a valid template (steps with steps[] or text with stepsText).

JSON output recipe (for any source)

• Produce either [{...}, {...}] or { "cases": [{...}] }.
• Use this per-case structure:

{
  "title": "...",
  "priority": "Low | Medium | High",
  "template": "steps | text",
  "estimate": "...",
  "preconditions": "...",
  "steps": [ { "action": "...", "expected": "..." } ],
  "stepsText": "..."
}

Import API (for programmatic use)

Endpoint used by the UI to bulk-create test cases:

• POST /api/project/{projectId}/test-cases/import
• Body:

{
  "suiteId": "string",
  "items": [
    {
      "title": "string",
      "priority": "Low | Medium | High",
      "template": "steps | text",
      "estimate": "string",
      "preconditions": "string",
      "steps": [ { "action": "string", "expected": "string" } ],
      "stepsText": "string"
    }
  ]
}

Response:

{ "data": [ { "id": "TC-1", "title": "..." } ], "created": 1 }

Sample files

Copy/paste from the examples above or export your spreadsheet to match the CSV headers. The UI also shows these templates in the Import dialog under Testing → Library.