Test case export
These three skills take the scenarios of a test plan to the project's test management
tool. The flow starts from a Markdown plan (the one generated by lippia-neo-create-test-plan):
lippia-neo-meta-normalize-test-cases converts it into a tool-agnostic test case format and
saves it as JSON next to the plan; lippia-neo-meta-export-test-cases takes that result and dispatches it to the
subskill for the tool declared in test_management.tool of qa-stack.yaml. Currently the only
available subskill is the one for Xray Cloud (lippia-neo-export-test-cases-xray); the one for QMetry
(lippia-neo-export-test-cases-qmetry) is pending: the router already recognizes it, but until
it's installed, exporting to QMetry returns blocked. No write to the tool happens
without human confirmation.
test plan (.md)
↓ lippia-neo-meta-normalize-test-cases → <us_id>-test-cases.json
↓ lippia-neo-meta-export-test-cases → reads test_management.tool from qa-stack.yaml
↓ lippia-neo-export-test-cases-xray (xray) · lippia-neo-export-test-cases-qmetry (qmetry, pending)
lippia-neo-meta-normalize-test-cases
When to use it
When you already have a test plan in Markdown and you want to take its scenarios to a
structured, tool-independent format, ready to import into Xray, Zephyr Scale,
TestRail, qTest, or Azure Test Plans. It doesn't parse the Markdown on its own: it delegates reading to
lippia-neo-read-test-plan and normalizes each scenario 1:1, copying texts, steps, priority, and
type exactly as they appear in the plan (it never makes them up or maps them to a fixed vocabulary). The
only transformation is moving a first step with no verifiable expected result
(—, -, N/A) to preconditions. It doesn't export anything or know the schema of any tool.
{
"input": {
"test_plan_path": "test-plans/LTM-21-test-plan.md"
}
}
| Input | Type | Description |
|---|---|---|
input.test_plan_path |
Required | Path (relative to the root of the test repository) to the Markdown plan. It's forwarded to lippia-neo-read-test-plan and defines where the output JSON is saved. |
Output
| Field | Description |
|---|---|
status |
normalized / failed. It fails if there's no path, reading the plan fails, the story identifier can't be resolved, there are no normalizable scenarios, or there are duplicate ids; in that case nothing is saved and the reason is the first warning. |
us_id |
Story identifier resolved by reading the plan (e.g. LTM-21), or null. |
test_cases |
One test case per scenario: id (the plan's, not renumbered), title, user_story (id + acceptance_criteria), priority, type, preconditions, steps (step, action, expected_result, test_data), test_data, and tags ([us_id, ...CA]). |
unparsed |
Scenarios that couldn't be normalized without ambiguity (no steps, a step with no action or no expected result), each with id and reason. They don't stop the rest. |
json_path |
Generated file, <plan directory>/<us_id>-test-cases.json (it warns before overwriting if it already exists); null if it failed. |
warnings |
Unspecified priority/type/data, plus the warnings from reading the plan with the prefix [read-test-plan] (including literals that look like a URL or credential inside the plan). |
Chains with
Runs on the plan generated by lippia-neo-create-test-plan (see planning)
and internally uses lippia-neo-read-test-plan. You normally don't invoke it yourself: it's called by
lippia-neo-meta-export-test-cases as its first step, although you can also run it on its own to
review the JSON before exporting.
lippia-neo-meta-export-test-cases
When to use it
It's the entry point for exporting a plan's test cases to the project's management
tool, or for previewing what would be created without writing anything. You pass it only the path to the plan:
it resolves the tool from test_management.tool of qa-stack.yaml (it never infers it from the
context), runs the plan through lippia-neo-meta-normalize-test-cases, and hands the test cases, without
touching them, to that tool's subskill. It's a router: it doesn't map fields, doesn't call APIs, doesn't
handle credentials, and doesn't answer the subskill's human confirmation. If there's no tool
configured, the value isn't supported, or the subskill isn't installed, it returns blocked
before normalizing.
{
"input": {
"test_plan_path": "test-plans/LTM-21-test-plan.md",
"mode": "preview"
}
}
| Input | Type | Description |
|---|---|---|
input.test_plan_path |
Required | Path to the Markdown test plan. It's forwarded to the normalizer and to the target subskill. |
input.mode |
Optional | dry-run / preview / export, forwarded as-is. If missing, the subskill's default applies (export, with its confirmation). |
input.approval_decision |
Optional | "approved" / "rejected": human confirmation already given, for non-interactive runs. It's forwarded as-is; it's never inferred. |
input.tool_overrides |
Optional | Specific overrides of the test_management.<tool> block of qa-stack.yaml; they're forwarded as input.<tool> (e.g. input.xray). |
Supported values of test_management.tool: xray (→ lippia-neo-export-test-cases-xray) and
qmetry (→ lippia-neo-export-test-cases-qmetry, pending: currently it returns blocked because the skill
isn't installed). Credentials don't go through this skill: each subskill takes them from its own environment.
Output
| Field | Description |
|---|---|
status |
blocked (no qa-stack.yaml, no tool, unsupported tool, or subskill not installed) / failed (no path, failed normalization, or no test cases) / or the subskill's status as-is: exported, partial, preview, dry_run, pending_approval, rejected. |
routing |
{ tool, skill, available }: tool read, resolved subskill, and whether it's installed. |
us_id |
Story identifier resolved by the normalizer, or null. |
test_plan_path |
The path received. |
normalization |
{ status, json_path, test_cases_count, unparsed }; null if it stopped before normalizing. |
export |
The subskill's output, unmodified; null if it never got to invoke it. |
summary |
One line with the tool, status, and totals (or the reason for the block/failure). |
warnings |
The router's, the normalizer's ([normalize]), and the subskill's ([export:<tool>]), including count differences between normalized and exported cases. |
Chains with
Receives the plan from lippia-neo-create-test-plan (see planning), invokes
lippia-neo-meta-normalize-test-cases, and dispatches to lippia-neo-export-test-cases-xray. The
test_management block of qa-stack.yaml can be generated by lippia-neo-bootstrap-stack (see
configuration and infrastructure).
lippia-neo-export-test-cases-xray
Subskill of lippia-neo-meta-export-test-cases
You don't need to invoke it directly: you invoke lippia-neo-meta-export-test-cases and this subskill is chosen automatically when test_management.tool of qa-stack.yaml is xray.
When to use it
When the project's test_management.tool is xray and you need to create in Xray Cloud the Tests
for a story from already-normalized test cases, or preview what would be created and what was already
exported. It creates one Manual Test per test case (bulk import), with the summary
<user_story.id> · <tc_id> — <title> and the unique label lippia-neo-test; optionally it
links them to the story's Jira issue and associates them with a Test Plan / Test Set. The mapping is done by
a deterministic script (scripts/xray-export.mjs, requires Node ≥ 20), always in the
order dry-run → preview → confirmation → export. Xray Cloud only: if the instance is
Server/Data Center, it aborts.
{
"input": {
"test_cases": [
{
"id": "TC-01",
"title": "Successful login with valid credentials",
"user_story": { "id": "US-001", "acceptance_criteria": ["CA-01"] },
"priority": "Alta",
"type": "Positivo",
"preconditions": "",
"steps": [
{ "step": 1, "action": "Navigate to /login", "expected_result": "Login page is visible", "test_data": null }
],
"test_data": null,
"tags": ["US-001", "CA-01"]
}
],
"requirement_key": "KAN-4",
"test_plan_path": "test-plans/US-001-test-plan.md",
"mode": "preview"
}
}
| Input | Type | Description |
|---|---|---|
input.test_cases |
Required | Array of normalized test cases (output of lippia-neo-meta-normalize-test-cases), passed to the script untouched. If it receives the normalizer's full object, it takes only test_cases. |
input.requirement_key |
Optional | Key of the story's Jira issue (e.g. KAN-4). Explicit only: if missing, the Tests aren't linked (it's never deduced from the us_id or the plan). It links all the Tests to that issue, so it's only allowed if all the test cases belong to the same story. |
input.test_plan_path |
Optional | Path to the source plan; for traceability only (it goes into the Test's description). |
input.mode |
Optional | dry-run (validates without network access and returns the payload) / preview (read-only against Xray) / export (default, with confirmation). |
input.approval_decision |
Optional | "approved" / "rejected" for non-interactive runs. Without a valid value, it returns pending_approval. |
input.xray |
Optional | Specific overrides of the test_management.xray block of qa-stack.yaml. |
Configuration in qa-stack.yaml (test_management.xray): project_key is mandatory;
optional are jira_base_url (to build links), requirement_link_type (default Test), test_plan
({ key }, { create: true, summary }, or null), test_set_key, folder, and on_existing (skip
by default; create generates duplicates). Without test_plan or test_set_key, no Test Plan or Test Set is
created or touched.
Credentials
XRAY_CLIENT_ID and XRAY_CLIENT_SECRET (mandatory for preview and export), and optionally
XRAY_BASE_URL for instances with data residency. They're generated in Jira (Apps → Xray → Settings →
API Keys) and go only in the project's paths.env_file file (gitignored), never in
qa-stack.yaml, in the chat, or in the request. If they're missing, the skill aborts and explains how to
configure them.
Output
| Field | Description |
|---|---|
status |
exported / partial (some created, others not) / preview / dry_run / pending_approval / rejected / failed. |
mode |
Mode it ran in: dry-run, preview, or export. |
project_key / requirement_key |
Jira project where the Tests live and the linked issue (or null). |
totals |
{ received, to_create, skipped_existing, created, failed }. |
created |
Created Tests: tc_id, user_story_id, key, issue_id, and url (if there's a jira_base_url). |
skipped |
Test cases already exported (same label + <us_id> · <tc_id> in the summary), which weren't duplicated, with their reason. |
errors |
Test cases that Xray rejected, with the API details. |
test_plan / test_set |
Association performed (key, action, added), or null. |
payload |
Only in dry-run / preview: the exact JSON that would be sent to Xray. |
summary / warnings |
Summary of the result and notices from the script and the skill. |
Limitations: a re-export doesn't update existing Tests (it skips them), only Manual Tests
are generated (not Cucumber or Generic), and it doesn't export execution results. Don't manually edit the summary
of an already-exported Test: if it loses <us_id> · <tc_id> (or the label), the next export will create it
again.
Chains with
It's invoked by lippia-neo-meta-export-test-cases when test_management.tool: xray, passing it the
test_cases from lippia-neo-meta-normalize-test-cases. You can also invoke it directly with an
already-normalized JSON; it's the only way to pass input.requirement_key, because the router doesn't
send that key.