Skip to content

Plugin⚓︎

The plugin offers several options for customizing the upload further.

Optional settings⚓︎

debug⚓︎

Turns on or off extensive debugging output.

Environment variable
PLUGIN_DEBUG
Type
boolean
Default
false
Example 
1
2
3
4
5
await configureXrayPlugin(on, config, {
    plugin: {
        debug: true
    },
});

1
npx cypress run --env PLUGIN_DEBUG=true

enabled⚓︎

Enables or disables the entire plugin. Setting this option to false disables all plugin functions, including authentication checks, uploads or feature file synchronization.

Environment variable
PLUGIN_ENABLED
Type
boolean
Default
true
Example 
1
2
3
4
5
await configureXrayPlugin(on, config, {
    plugin: {
        enabled: false
    },
});

1
npx cypress run --env PLUGIN_ENABLED=false

listener⚓︎

A listener function for handling plugin events, similar to the Cypress's setupNodeEvents function.

Type
function
Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
await configureXrayPlugin(on, config, {
    plugin: {
        listener: ({ on }) => {
            // Will be invoked as soon as the results have been uploaded:
            on("upload:cypress", (data) => {
                console.log(data.testExecutionIssueKey);
            });

            // Supports async callbacks, too:
            on("upload:cucumber", async (data) => {
                await writeFile("data.json", JSON.stringify(data));
            });
        }
    }
});

logDirectory⚓︎

The directory which all error and debug log files will be written to.

Environment variable
PLUGIN_LOG_DIRECTORY
Type
string
Default
"logs"
Example 
1
2
3
4
5
await configureXrayPlugin(on, config, {
    plugin: {
        logDirectory: "/home/logs"
    },
});

1
npx cypress run --env PLUGIN_LOG_DIRECTORY="/home/logs"

logger⚓︎

A custom logger function that replaces the default ANSI-based logger for the plugin. If specified, this logger will completely replace the default plugin logger.

Messages passed to this function:

  • will not contain the prefix │ Cypress Xray Plugin │

  • will not contain ANSI escape characters

  • may contain line break characters

Type
function
Example

The following example produces log messages with custom prefixes and debug messages that are only output if a corresponding environment variable is defined.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
await configureXrayPlugin(on, config, {
    plugin: {
        logger: (level, ...text) => {
            switch (level) {
                case "debug":
                    if (process.env.DEBUG) {
                      console.debug(...text);
                    }
                    break;
                case "error":
                    console.error("oh no", ...text);
                    break;
                case "info":
                    console.info("fyi", ...text);
                    break;
                case "notice":
                    console.log("please beware", ...text);
                    break;
                case "warning":
                    console.warn("danger", ...text);
                    break;
            }
        }
    },
});

normalizeScreenshotNames⚓︎

Some Xray setups might struggle with uploaded evidence if the filenames contain non-ASCII characters. With this option enabled, the plugin only keeps characters a-zA-Z0-9. in screenshot names and replaces all other sequences with _.

Environment variable
PLUGIN_NORMALIZE_SCREENSHOT_NAMES
Type
boolean
Default
false
Example 
1
2
3
4
5
await configureXrayPlugin(on, config, {
    plugin: {
        normalizeScreenshotNames: true
    },
});

1
npx cypress run --env PLUGIN_NORMALIZE_SCREENSHOT_NAMES=true

splitUpload⚓︎

Enables split upload mode for evidence files such as screenshots and videos, which are then uploaded in multiple smaller requests rather than in a single large request. This approach helps to avoid server-side request size limitations, and can also be useful for avoiding JSON.stringify token length errors.

If set to true, evidence uploads will be sent concurrently for each test issue. This may cause them to appear out of order in Xray. If the order is important, but split uploads are still desired, the sequential setting can be used.

Environment variable
PLUGIN_SPLIT_UPLOAD
Type
boolean or "sequential"
Default
false
Example 
1
2
3
4
5
await configureXrayPlugin(on, config, {
    plugin: {
        splitUpload: true
    },
});

1
npx cypress run --env PLUGIN_SPLIT_UPLOAD=true

uploadLastAttempt⚓︎

If set to true and test retries are enabled in Cypress, failed test attempts and their associated screenshots will be omitted from the upload to Xray, i.e. only the last attempt of each test will be included.

Environment variable
PLUGIN_UPLOAD_LAST_ATTEMPT
Type
boolean
Default
false
Example 
1
2
3
4
5
await configureXrayPlugin(on, config, {
    plugin: {
        uploadLastAttempt: true
    },
});

1
npx cypress run --env PLUGIN_UPLOAD_LAST_ATTEMPT=true