> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qa.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Xray

> Pull your existing Xray (Jira) tests into the QA.tech AI chat and turn them into tests

The Xray integration lets the [AI Chat Assistant](/core-concepts/ai-chat-assistant) read the tests you already keep in Xray, the test management app for Jira. You can browse them in chat and turn any of them into a QA.tech test without re-authoring the steps by hand. Nothing is synced in the background. Tests are fetched on demand when you ask for them.

<Note>
  **Xray Cloud only.** Xray Server and Data Center use a different API and are not
  supported.

  **Authentication:** an Xray API key (a Client ID and Client Secret pair).
  QA.tech uses these to mint a short-lived token internally and refreshes it for
  you. The Client Secret is stored encrypted and is never shown again after you
  save it.

  The Xray API key is separate from your Jira login. A Jira OAuth connection
  does not authenticate Xray, so you generate a dedicated key as shown below.

  **Region:** choose Global, United States, Europe, or Australia to match where
  your Xray Cloud data is hosted. Data-residency sites reject the global host.
</Note>

## How it compares to Custom MCP

Xray is a first-party integration: you enter your API key and QA.tech handles the connection, including token refresh. This is different from [Custom MCP servers](/core-concepts/ai-chat-assistant#custom-mcp-servers), where you bring your own MCP server. If you only need to read Xray tests into chat, use this integration. Use Custom MCP to connect a different MCP server, whether you host it yourself or point at a hosted one.

## Before you start

Generate an Xray API key in Jira. This requires an Xray administrator.

<Steps>
  <Step title="Open Xray API Keys">
    In Jira, go to **Apps → Xray → Global Settings → API Keys**.
  </Step>

  <Step title="Generate a key">
    Create an API key and copy its **Client ID** and **Client Secret**. Xray
    shows the secret only once. See the [Xray API Keys
    docs](https://docs.getxray.app/display/XRAYCLOUD/Global+Settings%3A+API+Keys)
    for details.
  </Step>
</Steps>

## Setup

<Steps>
  <Step title="Open the Xray integration">
    In your project, go to **Settings → Integrations** and select **Xray**.
  </Step>

  <Step title="Enter your credentials">
    Fill in:

    * **Region:** Global, United States, Europe, or Australia. Match your Xray
      Cloud data residency. Sites in the United States, Europe, or Australia
      fail if you leave this on Global.
    * **Client ID:** the client id from your Xray API key
    * **Client Secret:** the client secret from the same key

    Then click **Connect Xray**.
  </Step>

  <Step title="Test the connection">
    Click **Test connection** to confirm QA.tech can reach Xray. It reports how
    many tests it fetched against the total it can see, which confirms the key
    works and can read your tests.
  </Step>
</Steps>

To change the key or region later, open the integration and save. Leave the Client Secret field blank to keep the stored one.

## Using Xray in chat

Once connected, ask the [AI Chat Assistant](/core-concepts/ai-chat-assistant) to work with your Xray tests. It reads them through your project's API key.

| You ask for | What the assistant does |
| - | - |
| Tests in a Jira project | Lists tests for a project, paginated so large projects stay readable |
| Tests matching a query | Uses Jira query language (JQL) to select tests, for example by label or status |
| Tests in a repository folder | Narrows to a Test Repository folder path and its subfolders |
| A single test in full | Fetches the summary, description, labels, and steps for one test |
| A QA.tech test from an Xray test | Reads the test in full and drafts an equivalent QA.tech test |

Example prompts:

> "List the Xray tests in project ABC"

> "Find Xray tests labelled smoke in the Checkout folder"

> "Open Xray test ABC-123 and create an equivalent QA.tech test"

<Tip>
  Xray returns at most 100 tests per page, and a query that matches more than
  100 tests has to be narrowed. If a request is too broad, the assistant will
  scope it by project or folder, or page through the results, so you do not have
  to think about the limit.
</Tip>

### Test types it can read

Xray stores tests in a few shapes, and the assistant reads all of them:

* **Manual** tests, as ordered steps with actions and expected results.
* **Cucumber** tests, as their Gherkin scenario text.
* **Generic** tests, as their unstructured definition.

The test type comes across as context so the drafted QA.tech test matches the
original intent.

## Linked test cases

When you create a QA.tech test from an Xray test, the new test keeps a link back
to the test it came from.

* Before you approve the suggestion, the chat shows a **Reports results to** line
  with the source test, so you can catch a wrong link early.
* In your **Test Cases** list, the test shows an **Xray** badge next to its
  labels, for example `Xray ABC-123`.

<Note>
  The Xray badge is shown as plain text rather than a clickable link. The
  integration connects to the Xray API, which does not know your Jira site
  address, so QA.tech cannot build a reliable link to the issue in Jira. Use the
  Jira key on the badge to find the test in your own Jira.
</Note>

Duplicating or copying a linked test does not carry the link over, so two tests
never point at the same Xray test by accident.

## Limitations

| Supported | Not supported |
| - | - |
| Read tests on demand in chat | Background sync or webhooks |
| Select tests with JQL | Editing Xray tests from QA.tech |
| Narrow by Test Repository folder | Bulk import of a whole project in one action |
| Fetch one test in full, with steps or Gherkin | Pushing QA.tech run results back into Xray |
| Create a QA.tech test from an Xray test | A clickable Jira link on the badge |
| Xray Cloud | Xray Server or Data Center |

## Removing the integration

To disconnect, open **Settings → Integrations → Xray** and click **Remove**. This
deletes the stored credentials, including your Client Secret. Test cases you have
already created in QA.tech are not affected, and they keep their Xray badge.

## Related documentation

* [TestRail](/integrations/testrail): the same capability for TestRail cases
* [Jira](/integrations/jira): read Jira issues for PR reviews and test planning
* [Custom MCP servers](/core-concepts/ai-chat-assistant#custom-mcp-servers): connect any other MCP server, self-hosted or hosted
* [AI Chat Assistant](/core-concepts/ai-chat-assistant): where you work with your tests


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.