create-xray-test
File Cucumber scenarios you already have into Jira as Xray Test issues, or update the scenarios on an existing Xray Test, through the browser. Sets the parent epic, Components and the link to the story, and checks what was saved. Doesn't write or check scenarios; use live-verified-bdd to write them for a feature that already runs, or shape-epic for a new epic.
Beakpoint-Insights · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add Beakpoint-Insights/roost --skill create-xray-testAbout this skill
name: create-xray-test description: File Cucumber scenarios you already have into Jira as Xray Test issues, or update the scenarios on an existing Xray Test, through the browser. Sets the parent epic, Components and the link to the story, and checks what was saved. Doesn't write or check scenarios; use live-verified-bdd to write them for a feature that already runs, or shape-epic for a new epic.
Create Xray Test
Files Cucumber (Given/When/Then) scenarios into Jira Xray Test issues. The scenarios go in the Xray scenario editor, not the issue description.
This skill does the filing only. The scenarios come from:
shape-epic, for a new epic. It passes the approved test plan.live-verified-bdd, for a feature that already runs. It passes scenarios it has checked in the app.- The user, who pastes them.
If there are no scenarios yet, stop and use one of those first. Don't make scenarios up here.
First, load the team config with roost-config. This skill is the browser half of the Xray adapter (tests.kind: xray); the adapter's notes are in roost-config's references/tests-xray.md.
This skill is only for Xray. With another tests.kind, don't use it: create and update tests as that tests adapter's "Create a test" and "Update a test's scenarios" say (for eval cases, roost-config's references/tests-evals.md).
Prerequisites
- With
XRAY_CLIENT_IDandXRAY_CLIENT_SECRETset: nothing else. Use the API ("Creating tests through the API" below); no browser is needed. - Without them (the browser fallback): the Playwright MCP, with the user signed in to Jira in its browser. If they aren't, navigate to
https://<tracker.jira.site>and wait for them to sign in.
Input
- Epic key (for example PROJ-1768). Every test's parent is the epic.
- Story key for each test. A cross-cutting test (one that needs several slices) gets the last story it depends on.
- For a manual test (
tests.manual_label; see "Manual tests" in the Xray adapter notes): that it's manual, and its "how to run it" description. - Each test's title and its scenarios, in Gherkin.
- For an update: the existing test's key and its new scenarios.
Creating tests through the API
When XRAY_CLIENT_ID and XRAY_CLIENT_SECRET are set, create the tests and any Preconditions through Xray's API instead of the browser steps below: the Xray adapter notes (roost-config's references/tests-xray.md) show both mutations. It's faster and steadier than the browser. Show the user the list first, as below. Put the parent, the story's Components (step 6), and for a manual test its label and description, in the createTest call's jira.fields. Read every test back with getTests, comparing its Gherkin, labels and Components with what you sent; then link each test to its story (step 9). Use the browser steps only without the credentials.
Creating a test in the browser
Before creating anything, show the user the list of tests (key to be assigned, title, story, scenario names) and get approval. Then, for each test:
1. Open the create dialog
Click: css=[data-testid='atlassian-navigation--create-button']
Wait: 2 seconds for the dialog to load
The issue type stays "Test" after the first one in a session. If it isn't "Test", change it with the type selector.
2. Fill in the summary
Type into: css=[data-testid='issue-create-commons.common.ui.fields.base-fields.input-field.textfield']
Content: the test title (descriptive, under 100 characters)
3. Set the parent epic
The parent field only accepts epics, not stories.
Click: css=[data-testid='issue-create-commons.ui.pill-parent-field.parent-trigger']
Type into: css=input#parent-field
Content: the epic key
Wait: 2 seconds for search results
Click: css=#react-select-2-option-0
4. Create the issue
Click: css=[data-testid='issue-create-modernised.create-button']
Wait: 3 seconds
5. Get the key and open the test
Snapshot: css=[role='alert']
Extract: the issue key from the alert text (for example "Created Test PROJ-2281")
Click: the "View Test" link in the alert
Wait: 4 seconds for the page to load
6. Set Components
When tracker.components_required is true, every ticket needs Components. Copy them from the test's story (for a cross-cutting test, the last story it depends on) with the Jira MCP editJiraIssue tool. For a manual test, set its label and description in the same call (labels replace every label, so send them all):
fields: { "components": [{ "id": "<id>" }, …] }
fields: { "labels": ["<tests.manual_label>"], "description": "<how to run it>" } // manual tests only
7. Write the scenarios
The Xray panel lives in a Connect iframe whose URL contains all-in-one. The Ace editor's textarea is read-only, so fill() doesn't work. Set the editor's value through the frame instead:
const xrayFrame = page.frames().find(f => f.url().includes('all-in-one'));
await xrayFrame.locator('.ace_content').first().click(); // enter edit mode
await page.waitForTimeout(1500);
await xrayFrame.evaluate((g) => {
window.ace.edit(document.querySelector('.ace_editor')).setValue(g, -1);
}, gherkin);
await page.waitForTimeout(500);
await xrayFrame.getByRole('button', { name: 'Confirm' }).click();
On a new test, if there's no editor yet, click the "Click to add a scenario definition" element (test id gherkin-editor-view) first.
Never include a Feature: line. Xray builds the feature from the test summary. Start directly with Scenario::
Scenario: [what it proves]
Given [precondition]
When [action]
Then [expected result]
Scenario: [another behavior]
Given …
8. Check what was saved
Reload the page, wait about 7 seconds, read the editor's value again, and compare it with what you set:
const now = await xrayFrame.evaluate(() => window.ace.edit(document.querySelector('.ace_editor')).getValue());
I
Read the complete source ↗