> For the complete documentation index, see [llms.txt](https://docs.cloudbeat.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cloudbeat.io/features/test-case-links.md).

# Test Case Links (Jira, Xray and more)

Link test cases to Jira issues, Xray tests and test plans, Azure DevOps work items, TestRail cases or any URL, straight from your test code.

A test case can point to the items it covers in your ALM tools: the Xray test it reports to, the test plan it belongs to, the Jira story it verifies, a related bug. You declare these links in the test code; CloudBeat reads them every time the project syncs from git.

Each link has three parts:

| Part   | Values                                                                           |
| ------ | -------------------------------------------------------------------------------- |
| Source | `jira`, `xray`, `ado` (Azure DevOps), `testrail`, `url`                          |
| Type   | Optional: `epic`, `story`, `task`, `plan` (test plan), `case` (test case), `bug` |
| Value  | The issue key, work item ID or URL, e.g. `PROJ-123`                              |

The links appear on the test case's **Links** tab, under **External Links**. The type is shown as a tag next to the source, e.g. **Xray** `Test Plan`. Jira and Xray keys link to the issue when the Xray integration has a Jira host configured.

## Oxygen

Add one `oxygen-tags` comment to the test script (`.js` or `.ts`). Every word starting with `@` is a tag; tags of the form `@source=value` or `@source:type=value` are also links.

```javascript
// oxygen-tags: @smoke @xray=PROJ-123 @xray:plan=PROJ-50 @jira:story=PROJ-7
web.init();
web.open('https://example.com');
```

This test gets the tags `smoke`, `xray=PROJ-123`, `xray:plan=PROJ-50` and `jira:story=PROJ-7`, and three links: the Xray test `PROJ-123`, the Xray test plan `PROJ-50` and the Jira story `PROJ-7`.

More examples:

| Tag                           | Link                                     |
| ----------------------------- | ---------------------------------------- |
| `@xray=PROJ-123`              | Xray test `PROJ-123`                     |
| `@xray:plan=PROJ-50`          | Xray test plan `PROJ-50`                 |
| `@jira:story=PROJ-7`          | Jira story `PROJ-7`                      |
| `@ado:bug=4711`               | Azure DevOps bug `4711`                  |
| `@testrail:case=C1234`        | TestRail case `C1234`                    |
| `@url=https://wiki/spec`      | Link to `https://wiki/spec`              |
| `@url:spec=https://wiki/spec` | Link to `https://wiki/spec`, type `spec` |

Rules:

* Only the first `// oxygen-tags:` comment in the file is read. It does not have to be the first line.
* Tags are separated by spaces. A value cannot contain spaces; for several items, repeat the tag: `@xray=PROJ-1 @xray=PROJ-2`.
* The source and type are not case-sensitive. The value is kept as written, and may itself contain `:` or `=` (only the first `=` separates it).
* A type outside the list above is kept as written and shown as a tag, but has no special meaning in reporting.

{% hint style="info" %}
`@azure=` and `@link=` still work: they are the older names for `@ado=` and `@url=`.
{% endhint %}

## Java

Use the `@CbLink` annotation from `cb-kit-common` on a test method or class, or its shorthands `@CbXray` and `@CbJira`. All of them can be repeated.

```java
import io.cloudbeat.common.annotation.CbJira;
import io.cloudbeat.common.annotation.CbLink;
import io.cloudbeat.common.annotation.CbXray;

@CbXray("PROJ-123")
@CbXray(value = "PROJ-50", type = CbLink.TYPE_TEST_PLAN)
@CbJira(value = "PROJ-7", type = CbLink.TYPE_STORY)
@CbLink(value = "4711", source = CbLink.SRC_AZURE_DEVOPS, type = CbLink.TYPE_TEST_BUG)
@Test
public void loginTest() { ... }
```

The `SRC_*` and `TYPE_*` constants on `CbLink` hold the source and type values from the table above.

## Reporting results to Xray

When the Xray integration is enabled, CloudBeat reports each run's results to Xray. The link type decides how each Xray link is used:

* **Xray links without a type, or with type `case`**, are the Xray tests the result is reported against. A test case can report to several Xray tests.
* **Xray links with type `plan`** add the run's Test Execution to that test plan, provided all linked test cases in the run point to the same plan. When they point to different plans, the execution is not added to any of them.
* **Xray links with any other type** (`story`, `bug`, …) are shown on the test case but are not used for reporting.

{% hint style="warning" %}
Before typed links were supported, every Xray link was reported as a test. If your Xray links include test plans or other issues, add the type so they are no longer reported as test results.
{% endhint %}

A run can override these choices with environment variables, for example `XRAY-PLAN` to set the test plan or `XRAY-EXEC` to report into an existing Test Execution. `XRAY-PLAN` always wins over plan links. When a run reports into an existing Test Execution, plan links are not applied to it.
