Skip to content

FAQ⚓︎

Here is a list of common concerns or issues and how to deal with them.

Trusting custom root CAs⚓︎

In case an Xray instance is set up on an internal network with custom CA certificates, you will need to download these certificates and provide them to the Xray plugin.

Error messages requiring you to provide custom SSL certificates may look like any of the following:

Error: unable to get issuer certificate

Error: unable to verify the first certificate

Solution

Download the SSL certificate of your CA and make sure it is in .pem format. Then, tell the plugin to trust that CA by providing the certificate's path in the HTTP options:

1
2
3
4
5
6
7
8
9
import { Agent } from "node:https";

await configureXrayPlugin(on, config, {
    http: {
        httpsAgent: new Agent({
            ca: "/home/cert.pem",
        }),
    },
});

Providing security options⚓︎

Some web servers may be running outdated or legacy code, including the one on which your Xray instance is be installed. Modern HTTP clients usually reject communication attempts to communicate with such servers for security reasons. However, clients can be instructed to allow insecure communcation by setting appropriate flags.

Error messages that require you to provide security options may look like any of the following:

Error: unsafe legacy renegotiation disabled

Solution

Allow legacy insecure renegotiation between OpenSSL and unpatched clients or servers:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import { constants } from "node:crypto";
import { Agent } from "node:https";

await configureXrayPlugin(on, config, {
    http: {
        httpsAgent: new Agent({
            secureOptions: constants.SSL_OP_LEGACY_SERVER_CONNECT,
        }),
    },
});

Configuring a proxy⚓︎

Depending on your network infrastructure, you may need to configure proxy servers for the web requests that the plugin makes.

Error messages that require you to configure proxies may look like any of the following:

Error: Request failed with status code 502

Solution

You can configure a single proxy for all requests:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
await configureXrayPlugin(on, config, {
    http: {
        proxy: {
            host: 'http://1.2.3.4',
            port: 12345,
            auth: {
                username: 'johndoe',
                password: 'supersecret'
            }
        }
    },
});

You can configure a proxy for Jira only (and similarly for Xray):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
await configureXrayPlugin(on, config, {
    http: {
        jira: {
            proxy: {
                host: 'http://1.2.3.4',
                port: 12345,
                auth: {
                    username: 'johndoe',
                    password: 'supersecret'
                }
            }
        }
    },
});

You can also define different proxies for Jira and Xray:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
await configureXrayPlugin(on, config, {
    http: {
        jira: {
            proxy: {
                host: 'http://1.2.3.4',
                port: 12345,
                auth: {
                    username: 'johndoe',
                    password: 'supersecret'
                }
            }
        },
        xray: {
            proxy: {
                host: 'http://9.8.7.6',
                port: 98765,
                auth: {
                    username: 'johndoeAdmin',
                    password: 'supersecretButAdmin'
                }
            }
        }
    },
});

Assigning issues⚓︎

The way issues can be assigned may vary depending on your Jira version. Typically, Jira Cloud requires the assignee's account ID, whereas Jira Server requires the username (used to log in) instead.

The easiest way to retrieve this information is to find an existing issue where the desired assignee already appears somewhere in the fields (reporter, assignee) and then to export the issue to XML. You can then search the XML document for the desired person, which will usually appear in an HTML element.

Jira Server

Assuming that the XML export contains the following line...

1
<reporter username="jane.doe">Jane Doe</reporter>

... you may need to assign your test execution issues as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
await configureXrayPlugin(on, config, {
    jira: {
        testExecutionIssue: {
            fields: {
                assignee: {
                    name: 'jane.doe'
                }
            }
        }
    },
});

Jira Cloud

Assuming that the XML export contains the following line...

1
<reporter accountid="12345:4762614f-a4ea-42ad-ae93-e094702190d6">Jane Doe</reporter>

... you may need to assign your test execution issues as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
await configureXrayPlugin(on, config, {
    jira: {
        testExecutionIssue: {
            fields: {
                assignee: {
                    accountId: '12345:4762614f-a4ea-42ad-ae93-e094702190d6'
                }
            }
        }
    },
});

Error assembling issue data: expected Object containing a name property

Solution

Instead of assigning issues using the assignee's Jira ID or email address, you'll need to use their username instead (which they e.g. use to log in):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
await configureXrayPlugin(on, config, {
    jira: {
        testExecutionIssue: {
            fields: {
                assignee: {
                    name: 'username'
                }
            }
        }
    },
});

Rate limiting⚓︎

Jira Cloud and Xray Cloud use rate limiting in their APIs. If you're using Jira/Xray Server, your local server instance may also be rate limiting network requests. This can be a problem for larger projects, as the plugin processes as much concurrently as possible. For example, Cucumber feature files are all imported at the same time, as their imports do not affect each other.

Request failed with status code 429

Success

An easy way to avoid hitting API rate limits is to set a maximum number of requests per second.

The following configuration ensures that all requests (regardless of which API they are targeting) are sent every 200ms.

1
2
3
4
5
6
7
await configureXrayPlugin(on, config, {
    http: {
        rateLimiting: {
            requestsPerSecond: 5
        }
    },
});

The following configuration ensures that Jira requests are sent every 200ms, while Xray requests are sent once per second.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
await configureXrayPlugin(on, config, {
    http: {
        jira: {
            rateLimiting: {
                requestsPerSecond: 5
            }
        },
        xray: {
            rateLimiting: {
                requestsPerSecond: 1
            }
        }
    },
});