From bf57401e51edd7275c40236ee623d6e387de9446 Mon Sep 17 00:00:00 2001
From: AndrasEszes <andras.eszes@bitrise.io>
Date: Mon, 5 Oct 2026 18:09:43 +0200
Subject: [PATCH 1/6] Document linking test attachments by file name

The page now covers the file name convention that the Deploy to
Bitrise.io (2.26.0) and Export test results to Test Reports (1.3.0)
Steps use to link attachments to test cases. The manual attachment_*
properties stay documented as the alternative.

Every example is a one-time setup (a listener, a Gradle task, a
path builder, a reporter), so readers don't have to touch their
tests. Each was run against the Export Step's matcher. Tools that
could only be covered per test class or through deprecated or
private APIs (Paparazzi, Shot, Flutter) are left out.

The search_pattern examples name a single class XML on purpose: the
Export Step exports only its first match, and Gradle writes one XML
per test class.

CLAUDE.md listed only the languages added in docusaurus.config.ts,
which read as if JavaScript, TypeScript and XML blocks were not
highlighted. They come bundled with prism-react-renderer.
---
 CLAUDE.md                                     |   2 +-
 .../deploying-and-viewing-test-results.mdx    | 271 +++++++++++++++++-
 2 files changed, 269 insertions(+), 4 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 0bffbc6a..5602918f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -215,7 +215,7 @@ the same `slug:`).
 ### Code
 
 - Inline: backticks for filenames, command names, env var names. ``Open `bitrise.yml`.``
-- Blocks: triple backticks with a language hint (one of `yaml`, `bash`, `json`, `swift`, `kotlin`, `groovy`, `ruby`, `dart`, `diff` — those are the languages our Prism config loads).
+- Blocks: triple backticks with a language hint. `docusaurus.config.ts` adds `yaml`, `bash`, `json`, `swift`, `kotlin`, `groovy`, `ruby`, `dart`, `diff` on top of the languages `prism-react-renderer` bundles (among others `javascript`, `typescript`, `xml`, `go`, `python`). Use `text` for plain text, such as file names.
 - **Don't put code blocks inside admonitions.** Render the admonition first, then the code block as a sibling.
 
 **Showing a change to an existing file**
diff --git a/docs/bitrise-ci/testing/deploying-and-viewing-test-results.mdx b/docs/bitrise-ci/testing/deploying-and-viewing-test-results.mdx
index f724525b..5bf47ad3 100644
--- a/docs/bitrise-ci/testing/deploying-and-viewing-test-results.mdx
+++ b/docs/bitrise-ci/testing/deploying-and-viewing-test-results.mdx
@@ -50,7 +50,7 @@ If you run your tests using other Steps (for example, you can use [Script](https
 
    :::important[Attachments and flaky tests]
 
-   If your tests generate attachments or you want Bitrise to show flaky tests, the **Deploy to Bitrise.io** Step must be of version 2.19.1 or newer.
+   If your tests generate attachments or you want Bitrise to show flaky tests, the **Deploy to Bitrise.io** Step must be of version 2.19.1 or newer. To link attachments by file name, it must be version 2.26.0 or newer: [Naming attachments after their test case](/bitrise-ci/testing/deploying-and-viewing-test-results#naming-attachments-after-their-test-case).
 
    :::
 
@@ -102,7 +102,269 @@ Currently, we support the following file formats for attachments:
 
 :::
 
-However, if your test doesn't generate an `xcresult` file, you can still achieve the same thing by generating a JUnit XML file and using Bitrise Steps:
+If your tests don't generate an `xcresult` file, Bitrise can still show attachments under their test cases. There are two ways to link them:
+
+- Name each file after its test case: [Naming attachments after their test case](#naming-attachments-after-their-test-case).
+- Reference each file in the JUnit XML: [Referencing attachments in the JUnit XML](#referencing-attachments-in-the-junit-xml).
+
+### Naming attachments after their test case
+
+Name a screenshot, recording, or log after the test case that produced it, and Bitrise shows it under that test on the **Tests** tab. You don't have to edit the JUnit XML or write a script that links the files.
+
+:::important[Step versions]
+
+Linking attachments by file name requires the **Deploy to Bitrise.io** Step version 2.26.0 or newer. If you export your test results with the **Export test results to Test Reports** Step, it must be version 1.3.0 or newer.
+
+:::
+
+The file name has the following structure:
+
+```text
+<classname>__<name>[__run<k>]__<label>.<ext>
+```
+
+For example:
+
+```text
+com.example.LoginTest__emptyState__1.png
+com.example.LoginTest__wrongPassword__run2__api34.png
+com.example.LoginTest__wrongPassword__locked__1.png
+```
+
+The third file belongs to the test called `wrongPassword__locked`.
+
+| Part | Rule |
+|---|---|
+| `classname`, `name` | The `classname` and `name` attributes of the `<testcase>` element in your JUnit XML, case-sensitive. Replace each of the `" * / : < > ? \ \|` characters with `_`. |
+| `run<k>` | Optional. `k` is one or higher, and selects the k-th occurrence of the test case in its test suite: the **Run #k** card on the **Tests** tab. Without it, the file goes to the first run. |
+| `label` | Required. Any text that doesn't contain `__` and doesn't start with `_`: a counter (`1`), a device (`api34`), or both (`api34_1`). Attachments are sorted by label, with numbers in numeric order, so `2` comes before `10`. |
+| `ext` | One of `png`, `jpg`, `jpeg`, `mp4`, `webm`, `ogg`, `txt`, `log`, in any case. |
+
+Keep the following in mind:
+
+- Only the file name counts for matching, not the folder. The file still has to be somewhere the Steps look for it: [Exporting the attachments](#exporting-the-attachments).
+- A test name can contain `__`. If a test's own name ends in `__run<k>`, the file goes to that test, not to a run of another test.
+- When the same tests run more than once in a build, for example on two emulators, put the device in the label, such as the API level. Otherwise, the files overwrite each other or get skipped as copies.
+- If the same test case appears in more than one test suite of a report, its files aren't linked, because Bitrise can't tell which test case they belong to.
+- Attachment problems never fail the build. To find out why a file isn't linked, see [Troubleshooting missing attachments](#troubleshooting-missing-attachments).
+
+A file name can be at most 255 bytes on Linux and Android, and 255 characters on macOS. Long test names, such as parameterized tests or Kotlin test names written in backticks, can exceed this limit together with the label and the extension. Saving the file then fails in your own test code (`ENAMETOOLONG`). Bitrise doesn't shorten the names.
+
+#### Saving attachments from your test tool
+
+Set up the naming once, in your test configuration, so that you don't have to change your tests. Build the name from the same `classname` and `name` values that your JUnit reporter writes into the XML, replace the characters listed above, and always add a label. The following examples do this for some popular test tools.
+
+<Tabs>
+<TabItem value="android" label="Android" default>
+
+**AndroidX Test and Espresso**
+
+Register a JUnit `RunListener` once, through an instrumentation runner argument. Before each test, the listener installs an Espresso failure handler that takes a screenshot when an Espresso check fails, and saves it to test storage. The Android Gradle plugin then pulls the screenshot into `build/outputs/connected_android_test_additional_output/`.
+
+```kotlin
+// app/build.gradle.kts
+android {
+    defaultConfig {
+        testInstrumentationRunnerArguments["listener"] = "com.example.testing.BitriseScreenshotListener"
+        testInstrumentationRunnerArguments["useTestStorageService"] = "true"
+    }
+}
+
+dependencies {
+    androidTestUtil("androidx.test.services:test-services:1.6.0")
+}
+```
+
+```kotlin
+// app/src/androidTest/java/com/example/testing/BitriseScreenshotListener.kt
+package com.example.testing
+
+import android.os.Build
+import androidx.test.core.app.takeScreenshot
+import androidx.test.core.graphics.writeToTestStorage
+import androidx.test.espresso.Espresso
+import androidx.test.espresso.base.DefaultFailureHandler
+import androidx.test.platform.app.InstrumentationRegistry
+import org.junit.runner.Description
+import org.junit.runner.notification.RunListener
+
+private fun clean(value: String) = value.replace(Regex("""["*/:<>?\\|]"""), "_")
+
+class BitriseScreenshotListener : RunListener() {
+    override fun testStarted(test: Description) {
+        val default = DefaultFailureHandler(InstrumentationRegistry.getInstrumentation().targetContext)
+        Espresso.setFailureHandler { error, viewMatcher ->
+            val name = "${clean(test.className)}__${clean(test.methodName)}__api${Build.VERSION.SDK_INT}_failure"
+            takeScreenshot().writeToTestStorage(name)
+            default.handle(error, viewMatcher)
+        }
+    }
+}
+```
+
+Only failed Espresso checks get a screenshot, not plain JUnit assertions. The API level in the label keeps the screenshots of devices with different API levels apart.
+
+**Roborazzi**
+
+Add a task that copies Roborazzi's screenshots under the attachment name after each Roborazzi run. Roborazzi names its files `<class>.<method>.png`, so the task can rename them without any change to your tests:
+
+```kotlin
+// app/build.gradle.kts
+val bitriseScreenshots by tasks.registering(Sync::class) {
+    from(layout.buildDirectory.dir("outputs/roborazzi")) { include("*.png") }
+    into(layout.buildDirectory.dir("bitrise-screenshots"))
+    rename("""(.+)\.([^.]+?)(?:_(\d+))?(_actual|_compare)?\.png""", "$1__$2__screenshot$3$4.png")
+}
+tasks.named { it == "finalizeTestRoborazziDebug" }.configureEach { finalizedBy(bitriseScreenshots) }
+```
+
+Roborazzi only writes screenshots when you run `recordRoborazziDebug`, `verifyRoborazziDebug`, or `compareRoborazziDebug`. Parameterized tests don't get attachments, because Roborazzi doesn't put the parameters in the file name.
+
+</TabItem>
+<TabItem value="react-native" label="React Native">
+
+**Detox**
+
+Detox names every per-test artifact, such as screenshots, videos, and logs, through a path builder. With its default templates, jest-junit writes the describe blocks and the test title into both `classname` and `name`, so the path builder can rebuild them from the test's title and full name. Point `artifacts.pathBuilder` in your Detox configuration to this file:
+
+```javascript
+// e2e/bitrisePathBuilder.js
+const path = require('path');
+
+const clean = (value) => value.replace(/["*/:<>?\\|]/g, '_');
+
+module.exports = class BitrisePathBuilder {
+  constructor({ rootDir }) {
+    this.rootDir = rootDir;
+  }
+
+  buildPathForTestArtifact(artifactName, testSummary) {
+    if (!testSummary) return path.join(this.rootDir, artifactName);
+
+    const { title, fullName } = testSummary;
+    const key = clean(`${fullName.slice(0, -title.length).trim()} ${title}`);
+    const ext = path.extname(artifactName);
+    const label = path.basename(artifactName, ext).replace(/_+/g, '_').replace(/^_/, '');
+    return path.join(this.rootDir, `${key}__${key}__${label}${ext}`);
+  }
+};
+```
+
+Because the full test name appears twice, long test names reach the file name length limit sooner.
+
+</TabItem>
+<TabItem value="web" label="Web">
+
+**Playwright**
+
+Add a reporter that copies the screenshots and videos Playwright attaches to a test under the attachment name. The junit reporter writes the spec file as `classname`, and the describe blocks and the test title as `name`. Turn on `includeProjectInTestName`, so that each project writes its own test case. Without it, every project writes the same test case, and none of them gets attachments:
+
+```typescript
+// playwright.config.ts
+reporter: [
+  ['junit', { outputFile: 'test-results/junit.xml', includeProjectInTestName: true }],
+  ['./bitrise-reporter.ts'],
+],
+use: { screenshot: 'only-on-failure', video: 'retain-on-failure' },
+```
+
+```typescript
+// bitrise-reporter.ts
+import fs from 'node:fs';
+import path from 'node:path';
+import type { Reporter, TestCase, TestResult } from '@playwright/test/reporter';
+
+const clean = (value: string) => value.replace(/["*/:<>?\\|]/g, '_');
+const supported = /\.(png|jpe?g|mp4|webm|ogg|txt|log)$/i;
+
+export default class BitriseAttachments implements Reporter {
+  onTestEnd(test: TestCase, result: TestResult) {
+    const [, project, file, ...titles] = test.titlePath();
+    const key = `${clean(file)}__${clean((project ? `[${project}] ` : '') + titles.join(' › '))}`;
+    const files = result.attachments.filter((a) => a.path && supported.test(a.path));
+    files.forEach((a, i) => {
+      const label = (result.retry ? `retry${result.retry}_` : '') + (i + 1);
+      const target = path.join('test-attachments', `${key}__${label}${path.extname(a.path!)}`);
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.copyFileSync(a.path!, target);
+    });
+  }
+}
+```
+
+A retried test stays one test case in the XML, so the reporter puts the retry in the label instead of using `run<k>`.
+
+</TabItem>
+</Tabs>
+
+#### Exporting the attachments
+
+If you run your tests with a Script Step or another Step that doesn't export its own results, the **Export test results to Test Reports** Step exports the attachments together with the JUnit XML.
+
+<Tabs>
+<TabItem value="workflow-editor" label="Workflow Editor" default>
+
+1. <Partial_OpeningTheWorkflowEditor />
+1. Add the **Export test results to Test Reports** Step to your Workflow after the Step that runs your tests.
+1. In the **Test result base path** input, set a folder that contains both your test results and your attachments, for example `app/build/`.
+
+   The Step looks for attachments only in this folder. If it points to the folder of the XML, for example `app/build/test-results/`, the Step doesn't find screenshots saved elsewhere.
+1. In the **Test result search pattern** input, set a pattern that matches a single JUnit XML, for example `*/test-results/testDemoDebugUnitTest/TEST-com.example.ScreenshotTest.xml`.
+
+   The Step exports only the first match. A wider base path makes it more likely that the pattern matches more than one file. Gradle writes a separate XML for each test class, so only the tests and attachments of the matched class show up.
+1. Make sure you have the **Deploy to Bitrise.io** Step at the end of your Workflow.
+
+</TabItem>
+<TabItem value="configuration-yaml" label="Configuration YAML">
+
+1. Add the `custom-test-results-export` Step to your Workflow after the Step that runs your tests.
+1. Set `base_path` to a folder that contains both your test results and your attachments, and set `search_pattern` to a pattern that matches a single JUnit XML.
+
+   The Step looks for attachments only in `base_path`, and exports only the first match of `search_pattern`. Gradle writes a separate XML for each test class, so only the tests and attachments of the matched class show up.
+1. Add the `deploy-to-bitrise-io` Step to the end of your Workflow.
+
+   ```yaml
+   workflows:
+     screenshot-tests:
+       steps:
+       - script@1:
+           inputs:
+           - content: ./gradlew testDebugUnitTest
+       - custom-test-results-export@1:
+           inputs:
+           - test_name: screenshot_tests
+           - base_path: app/build/
+           - search_pattern: "*/test-results/testDebugUnitTest/TEST-com.example.ScreenshotTest.xml"
+       - deploy-to-bitrise-io@2: {}
+   ```
+
+</TabItem>
+</Tabs>
+
+After exporting the XML, the Step copies every file whose name matches a test case in that XML into the report. It skips the following files:
+
+- Files tracked by git, such as committed reference images
+- Files in dependency and tool folders, such as `.git`, `node_modules`, `Pods`, and `.dart_tool`
+- Files that an earlier Step already exported
+
+Outside a git repository, the Step logs a warning and doesn't filter out committed files.
+
+If you copy the files into the report folder yourself, for example with a Script Step, the **Deploy to Bitrise.io** Step links them by name, too.
+
+#### Troubleshooting missing attachments
+
+The Steps report attachment problems in the build log:
+
+- If a file name doesn't match any test case, for example because of a typo or a missing label, the **Export test results to Test Reports** Step skips the file without a warning. To see which files it skipped and why, set its **Enable verbose logging?** input to `yes`.
+- If the **Export test results to Test Reports** Step finds a matching file but can't link it, for example because more than one file has the same name, it logs `Skipping attachment <file>: <reason>`.
+- If the **Deploy to Bitrise.io** Step can't link a file in the report folder, it logs `Test attachment <file> is not linked to a test case: <reason>`.
+- Use a lowercase `.xml` extension for your JUnit XML. Bitrise doesn't recognize test results with an uppercase `.XML` extension.
+- The **Export test results to Test Reports** Step exports `.junit` test results without attachments.
+- Bitrise drops `attachment_*` properties on a `<testsuite>` element. Add them to the `<testcase>` element instead.
+
+### Referencing attachments in the JUnit XML
+
+If you can't name the files after their test cases, reference them in the JUnit XML instead:
 
 <Tabs>
 <TabItem value="workflow-editor" label="Workflow Editor" default>
@@ -249,6 +511,8 @@ With the correct configuration, the Step finds the test results in your project
 
    - If your project’s root directory is `app`: `app/build/test-results/testDemoDebugUnitTest/`
    - If your test results are within a project folder but `app` is not the root directory: ./app/build/test-results/testDemoDebugUnitTest/
+
+   The Step also looks for [attachments named after their test case](/bitrise-ci/testing/deploying-and-viewing-test-results#naming-attachments-after-their-test-case) in this folder. If your tests save attachments, such as screenshots, outside this folder, set a folder that contains both, for example `app/build/`. Then make the search pattern in the next input specific enough to match a single test result.
 1. In the **Test result search pattern** input, set a pattern that matches your test result file.
 
    This search pattern is used to search every file and folder of the path that was set in the **Path where custom test results reside** input.
@@ -259,9 +523,10 @@ With the correct configuration, the Step finds the test results in your project
 
    - Matching all files within the base path: `*`
    - Matching all files within a given directory of the base path: `*/build/test-results/testDemoDebugUnitTest/*`
+   - Matching a single JUnit XML when the base path is a wider folder, such as `app/build/`: `*/test-results/testDemoDebugUnitTest/TEST-com.example.ScreenshotTest.xml`
 1. In the **Step’s test result directory** input, make sure the path is correct.
 
    Do NOT modify this input’s value: this is the folder where the **Deploy to Bitrise.io** Step will look for the test results to export them. It should be set to the `$BITRISE_TEST_RESULT_DIR` Env Var.
 1. Make sure you have a **Deploy to Bitrise.io** Step in your Workflow.
 
-   If your tests generate attachments, make sure the Step is of version 2.19.x or newer.
+   If your tests generate attachments, make sure the Step is of version 2.19.x or newer. To link attachments by file name, use version 2.26.0 or newer.

From a5582fcdaff56ad0afac14594987127b0db5602b Mon Sep 17 00:00:00 2001
From: AndrasEszes <andras.eszes@bitrise.io>
Date: Tue, 6 Oct 2026 11:04:35 +0200
Subject: [PATCH 2/6] Trim the attachment naming section

Readers found the section hard to scan. The convention is now four
rules, each tool gets one sentence and its code, and the Export Step
setup and version requirements are stated once instead of three times.

Edge cases that rarely matter (a test name ending in __run<k>, the
255-byte file name limit, .XML and .junit results, testsuite-level
properties, git filtering details) are left out. The rule to put the
device in the label stays, since every multi-device run hits it.
---
 .../deploying-and-viewing-test-results.mdx    | 124 ++++--------------
 1 file changed, 22 insertions(+), 102 deletions(-)

diff --git a/docs/bitrise-ci/testing/deploying-and-viewing-test-results.mdx b/docs/bitrise-ci/testing/deploying-and-viewing-test-results.mdx
index 5bf47ad3..2789be19 100644
--- a/docs/bitrise-ci/testing/deploying-and-viewing-test-results.mdx
+++ b/docs/bitrise-ci/testing/deploying-and-viewing-test-results.mdx
@@ -50,7 +50,7 @@ If you run your tests using other Steps (for example, you can use [Script](https
 
    :::important[Attachments and flaky tests]
 
-   If your tests generate attachments or you want Bitrise to show flaky tests, the **Deploy to Bitrise.io** Step must be of version 2.19.1 or newer. To link attachments by file name, it must be version 2.26.0 or newer: [Naming attachments after their test case](/bitrise-ci/testing/deploying-and-viewing-test-results#naming-attachments-after-their-test-case).
+   If your tests generate attachments or you want Bitrise to show flaky tests, the **Deploy to Bitrise.io** Step must be of version 2.19.1 or newer.
 
    :::
 
@@ -109,57 +109,35 @@ If your tests don't generate an `xcresult` file, Bitrise can still show attachme
 
 ### Naming attachments after their test case
 
-Name a screenshot, recording, or log after the test case that produced it, and Bitrise shows it under that test on the **Tests** tab. You don't have to edit the JUnit XML or write a script that links the files.
+Name a screenshot, recording, or log after the test case that produced it, and Bitrise shows it under that test on the **Tests** tab.
 
 :::important[Step versions]
 
-Linking attachments by file name requires the **Deploy to Bitrise.io** Step version 2.26.0 or newer. If you export your test results with the **Export test results to Test Reports** Step, it must be version 1.3.0 or newer.
+This requires the **Deploy to Bitrise.io** Step version 2.26.0 or newer. If you use the **Export test results to Test Reports** Step, it must be version 1.3.0 or newer.
 
 :::
 
-The file name has the following structure:
+The file name has the following structure, for example `com.example.LoginTest__emptyState__1.png`:
 
 ```text
 <classname>__<name>[__run<k>]__<label>.<ext>
 ```
 
-For example:
+- Copy `classname` and `name` from the `<testcase>` element of your JUnit XML, and replace any of the `" * / : < > ? \ |` characters with `_`.
+- Always add a label, such as a counter. The label can't contain `__` or start with `_`.
+- If the same tests run on more than one device, put the device in the label, for example `api34_1`. Otherwise, the files overwrite each other.
+- To attach a file to a later run of the same test case, add `__run2`, `__run3`, and so on before the label.
 
-```text
-com.example.LoginTest__emptyState__1.png
-com.example.LoginTest__wrongPassword__run2__api34.png
-com.example.LoginTest__wrongPassword__locked__1.png
-```
-
-The third file belongs to the test called `wrongPassword__locked`.
-
-| Part | Rule |
-|---|---|
-| `classname`, `name` | The `classname` and `name` attributes of the `<testcase>` element in your JUnit XML, case-sensitive. Replace each of the `" * / : < > ? \ \|` characters with `_`. |
-| `run<k>` | Optional. `k` is one or higher, and selects the k-th occurrence of the test case in its test suite: the **Run #k** card on the **Tests** tab. Without it, the file goes to the first run. |
-| `label` | Required. Any text that doesn't contain `__` and doesn't start with `_`: a counter (`1`), a device (`api34`), or both (`api34_1`). Attachments are sorted by label, with numbers in numeric order, so `2` comes before `10`. |
-| `ext` | One of `png`, `jpg`, `jpeg`, `mp4`, `webm`, `ogg`, `txt`, `log`, in any case. |
-
-Keep the following in mind:
-
-- Only the file name counts for matching, not the folder. The file still has to be somewhere the Steps look for it: [Exporting the attachments](#exporting-the-attachments).
-- A test name can contain `__`. If a test's own name ends in `__run<k>`, the file goes to that test, not to a run of another test.
-- When the same tests run more than once in a build, for example on two emulators, put the device in the label, such as the API level. Otherwise, the files overwrite each other or get skipped as copies.
-- If the same test case appears in more than one test suite of a report, its files aren't linked, because Bitrise can't tell which test case they belong to.
-- Attachment problems never fail the build. To find out why a file isn't linked, see [Troubleshooting missing attachments](#troubleshooting-missing-attachments).
+#### Setting up your test tool
 
-A file name can be at most 255 bytes on Linux and Android, and 255 characters on macOS. Long test names, such as parameterized tests or Kotlin test names written in backticks, can exceed this limit together with the label and the extension. Saving the file then fails in your own test code (`ENAMETOOLONG`). Bitrise doesn't shorten the names.
-
-#### Saving attachments from your test tool
-
-Set up the naming once, in your test configuration, so that you don't have to change your tests. Build the name from the same `classname` and `name` values that your JUnit reporter writes into the XML, replace the characters listed above, and always add a label. The following examples do this for some popular test tools.
+Set up the naming once, in your test configuration. The following examples work without changing your tests:
 
 <Tabs>
 <TabItem value="android" label="Android" default>
 
 **AndroidX Test and Espresso**
 
-Register a JUnit `RunListener` once, through an instrumentation runner argument. Before each test, the listener installs an Espresso failure handler that takes a screenshot when an Espresso check fails, and saves it to test storage. The Android Gradle plugin then pulls the screenshot into `build/outputs/connected_android_test_additional_output/`.
+Register a `RunListener` that takes a screenshot when an Espresso check fails:
 
 ```kotlin
 // app/build.gradle.kts
@@ -202,11 +180,11 @@ class BitriseScreenshotListener : RunListener() {
 }
 ```
 
-Only failed Espresso checks get a screenshot, not plain JUnit assertions. The API level in the label keeps the screenshots of devices with different API levels apart.
+Plain JUnit assertions don't get a screenshot.
 
 **Roborazzi**
 
-Add a task that copies Roborazzi's screenshots under the attachment name after each Roborazzi run. Roborazzi names its files `<class>.<method>.png`, so the task can rename them without any change to your tests:
+Copy Roborazzi's screenshots under the attachment name after each Roborazzi run:
 
 ```kotlin
 // app/build.gradle.kts
@@ -218,14 +196,14 @@ val bitriseScreenshots by tasks.registering(Sync::class) {
 tasks.named { it == "finalizeTestRoborazziDebug" }.configureEach { finalizedBy(bitriseScreenshots) }
 ```
 
-Roborazzi only writes screenshots when you run `recordRoborazziDebug`, `verifyRoborazziDebug`, or `compareRoborazziDebug`. Parameterized tests don't get attachments, because Roborazzi doesn't put the parameters in the file name.
+Roborazzi writes screenshots only when you run `recordRoborazziDebug`, `verifyRoborazziDebug`, or `compareRoborazziDebug`. Parameterized tests don't get attachments.
 
 </TabItem>
 <TabItem value="react-native" label="React Native">
 
 **Detox**
 
-Detox names every per-test artifact, such as screenshots, videos, and logs, through a path builder. With its default templates, jest-junit writes the describe blocks and the test title into both `classname` and `name`, so the path builder can rebuild them from the test's title and full name. Point `artifacts.pathBuilder` in your Detox configuration to this file:
+Point `artifacts.pathBuilder` in your Detox configuration to this file. It names every screenshot, video, and log the way jest-junit names the test with its default settings:
 
 ```javascript
 // e2e/bitrisePathBuilder.js
@@ -250,14 +228,12 @@ module.exports = class BitrisePathBuilder {
 };
 ```
 
-Because the full test name appears twice, long test names reach the file name length limit sooner.
-
 </TabItem>
 <TabItem value="web" label="Web">
 
 **Playwright**
 
-Add a reporter that copies the screenshots and videos Playwright attaches to a test under the attachment name. The junit reporter writes the spec file as `classname`, and the describe blocks and the test title as `name`. Turn on `includeProjectInTestName`, so that each project writes its own test case. Without it, every project writes the same test case, and none of them gets attachments:
+Turn on `includeProjectInTestName` for the junit reporter, and add a reporter that copies the screenshots and videos of each test under the attachment name:
 
 ```typescript
 // playwright.config.ts
@@ -292,75 +268,19 @@ export default class BitriseAttachments implements Reporter {
 }
 ```
 
-A retried test stays one test case in the XML, so the reporter puts the retry in the label instead of using `run<k>`.
-
 </TabItem>
 </Tabs>
 
 #### Exporting the attachments
 
-If you run your tests with a Script Step or another Step that doesn't export its own results, the **Export test results to Test Reports** Step exports the attachments together with the JUnit XML.
-
-<Tabs>
-<TabItem value="workflow-editor" label="Workflow Editor" default>
-
-1. <Partial_OpeningTheWorkflowEditor />
-1. Add the **Export test results to Test Reports** Step to your Workflow after the Step that runs your tests.
-1. In the **Test result base path** input, set a folder that contains both your test results and your attachments, for example `app/build/`.
-
-   The Step looks for attachments only in this folder. If it points to the folder of the XML, for example `app/build/test-results/`, the Step doesn't find screenshots saved elsewhere.
-1. In the **Test result search pattern** input, set a pattern that matches a single JUnit XML, for example `*/test-results/testDemoDebugUnitTest/TEST-com.example.ScreenshotTest.xml`.
-
-   The Step exports only the first match. A wider base path makes it more likely that the pattern matches more than one file. Gradle writes a separate XML for each test class, so only the tests and attachments of the matched class show up.
-1. Make sure you have the **Deploy to Bitrise.io** Step at the end of your Workflow.
-
-</TabItem>
-<TabItem value="configuration-yaml" label="Configuration YAML">
-
-1. Add the `custom-test-results-export` Step to your Workflow after the Step that runs your tests.
-1. Set `base_path` to a folder that contains both your test results and your attachments, and set `search_pattern` to a pattern that matches a single JUnit XML.
-
-   The Step looks for attachments only in `base_path`, and exports only the first match of `search_pattern`. Gradle writes a separate XML for each test class, so only the tests and attachments of the matched class show up.
-1. Add the `deploy-to-bitrise-io` Step to the end of your Workflow.
-
-   ```yaml
-   workflows:
-     screenshot-tests:
-       steps:
-       - script@1:
-           inputs:
-           - content: ./gradlew testDebugUnitTest
-       - custom-test-results-export@1:
-           inputs:
-           - test_name: screenshot_tests
-           - base_path: app/build/
-           - search_pattern: "*/test-results/testDebugUnitTest/TEST-com.example.ScreenshotTest.xml"
-       - deploy-to-bitrise-io@2: {}
-   ```
-
-</TabItem>
-</Tabs>
-
-After exporting the XML, the Step copies every file whose name matches a test case in that XML into the report. It skips the following files:
-
-- Files tracked by git, such as committed reference images
-- Files in dependency and tool folders, such as `.git`, `node_modules`, `Pods`, and `.dart_tool`
-- Files that an earlier Step already exported
-
-Outside a git repository, the Step logs a warning and doesn't filter out committed files.
-
-If you copy the files into the report folder yourself, for example with a Script Step, the **Deploy to Bitrise.io** Step links them by name, too.
+If you use the **Export test results to Test Reports** Step, set its **Test result base path** input to a folder that contains both your test results and your attachments, for example `app/build/`. See [Using the Export test results to Test Reports Step](#using-the-export-test-results-to-test-reports-step).
 
 #### Troubleshooting missing attachments
 
-The Steps report attachment problems in the build log:
+If an attachment doesn't show up, check the build log:
 
-- If a file name doesn't match any test case, for example because of a typo or a missing label, the **Export test results to Test Reports** Step skips the file without a warning. To see which files it skipped and why, set its **Enable verbose logging?** input to `yes`.
-- If the **Export test results to Test Reports** Step finds a matching file but can't link it, for example because more than one file has the same name, it logs `Skipping attachment <file>: <reason>`.
-- If the **Deploy to Bitrise.io** Step can't link a file in the report folder, it logs `Test attachment <file> is not linked to a test case: <reason>`.
-- Use a lowercase `.xml` extension for your JUnit XML. Bitrise doesn't recognize test results with an uppercase `.XML` extension.
-- The **Export test results to Test Reports** Step exports `.junit` test results without attachments.
-- Bitrise drops `attachment_*` properties on a `<testsuite>` element. Add them to the `<testcase>` element instead.
+- The **Export test results to Test Reports** Step skips files that don't match a test case without a warning. To list them, set its **Enable verbose logging?** input to `yes`.
+- The **Deploy to Bitrise.io** Step logs a warning for every file in the report that it can't link to a test case.
 
 ### Referencing attachments in the JUnit XML
 
@@ -512,7 +432,7 @@ With the correct configuration, the Step finds the test results in your project
    - If your project’s root directory is `app`: `app/build/test-results/testDemoDebugUnitTest/`
    - If your test results are within a project folder but `app` is not the root directory: ./app/build/test-results/testDemoDebugUnitTest/
 
-   The Step also looks for [attachments named after their test case](/bitrise-ci/testing/deploying-and-viewing-test-results#naming-attachments-after-their-test-case) in this folder. If your tests save attachments, such as screenshots, outside this folder, set a folder that contains both, for example `app/build/`. Then make the search pattern in the next input specific enough to match a single test result.
+   To export [attachments named after their test case](/bitrise-ci/testing/deploying-and-viewing-test-results#naming-attachments-after-their-test-case), set a folder that contains both your test results and your attachments, for example `app/build/`.
 1. In the **Test result search pattern** input, set a pattern that matches your test result file.
 
    This search pattern is used to search every file and folder of the path that was set in the **Path where custom test results reside** input.
@@ -529,4 +449,4 @@ With the correct configuration, the Step finds the test results in your project
    Do NOT modify this input’s value: this is the folder where the **Deploy to Bitrise.io** Step will look for the test results to export them. It should be set to the `$BITRISE_TEST_RESULT_DIR` Env Var.
 1. Make sure you have a **Deploy to Bitrise.io** Step in your Workflow.
 
-   If your tests generate attachments, make sure the Step is of version 2.19.x or newer. To link attachments by file name, use version 2.26.0 or newer.
+   If your tests generate attachments, make sure the Step is of version 2.19.x or newer.

From 3381ea4d8b986cfef1bcfd837ff7b14dc62d714f Mon Sep 17 00:00:00 2001
From: AndrasEszes <andras.eszes@bitrise.io>
Date: Tue, 6 Oct 2026 15:56:37 +0200
Subject: [PATCH 3/6] Add Paparazzi and give each tool its own tab

Paparazzi runs in more workspaces than Roborazzi, so it gets an
example even though it needs a shared rule factory instead of a
one-time setup: Paparazzi has no global hook, and its own file names
can't be mapped back to the test case unambiguously.

The example targets 1.3.5, the stable release. On AGP 8 with
kotlin-android the handler needs noJdk off to see java.awt, and
without outputs.dir a build-cache hit restores the XML but not the
snapshots, so nothing gets linked.
---
 .../deploying-and-viewing-test-results.mdx    | 80 ++++++++++++++++---
 1 file changed, 69 insertions(+), 11 deletions(-)

diff --git a/docs/bitrise-ci/testing/deploying-and-viewing-test-results.mdx b/docs/bitrise-ci/testing/deploying-and-viewing-test-results.mdx
index 2789be19..1adc5279 100644
--- a/docs/bitrise-ci/testing/deploying-and-viewing-test-results.mdx
+++ b/docs/bitrise-ci/testing/deploying-and-viewing-test-results.mdx
@@ -130,12 +130,10 @@ The file name has the following structure, for example `com.example.LoginTest__e
 
 #### Setting up your test tool
 
-Set up the naming once, in your test configuration. The following examples work without changing your tests:
+Set up the naming once, in your test configuration. The following examples do this for some popular test tools:
 
 <Tabs>
-<TabItem value="android" label="Android" default>
-
-**AndroidX Test and Espresso**
+<TabItem value="espresso" label="Espresso" default>
 
 Register a `RunListener` that takes a screenshot when an Espresso check fails:
 
@@ -182,7 +180,71 @@ class BitriseScreenshotListener : RunListener() {
 
 Plain JUnit assertions don't get a screenshot.
 
-**Roborazzi**
+</TabItem>
+<TabItem value="paparazzi" label="Paparazzi">
+
+Create your Paparazzi rules through a shared function that adds a snapshot handler. The handler saves every snapshot under the attachment name as well:
+
+```kotlin
+// src/test/java/com/example/testing/BitrisePaparazzi.kt
+package com.example.testing
+
+import app.cash.paparazzi.DeviceConfig
+import app.cash.paparazzi.HtmlReportWriter
+import app.cash.paparazzi.Paparazzi
+import app.cash.paparazzi.Snapshot
+import app.cash.paparazzi.SnapshotHandler
+import app.cash.paparazzi.SnapshotVerifier
+import java.awt.image.BufferedImage
+import java.io.File
+import javax.imageio.ImageIO
+
+private fun clean(value: String) = value.replace(Regex("""["*/:<>?\\|]"""), "_")
+
+fun bitrisePaparazzi(deviceConfig: DeviceConfig = DeviceConfig.PIXEL_5) =
+    Paparazzi(deviceConfig = deviceConfig, snapshotHandler = BitriseSnapshotHandler())
+
+class BitriseSnapshotHandler(
+    maxPercentDifference: Double = 0.1,
+    private val delegate: SnapshotHandler =
+        if (System.getProperty("paparazzi.test.verify") == "true") SnapshotVerifier(maxPercentDifference)
+        else HtmlReportWriter(),
+) : SnapshotHandler by delegate {
+    override fun newFrameHandler(snapshot: Snapshot, frameCount: Int, fps: Int): SnapshotHandler.FrameHandler {
+        val frames = delegate.newFrameHandler(snapshot, frameCount, fps)
+        val test = snapshot.testName
+        val label = snapshot.name?.replace(Regex("_+"), "_")?.removePrefix("_") ?: "snapshot"
+        val name = "${clean("${test.packageName}.${test.className}")}__${clean(test.methodName)}__$label"
+        val file = File(System.getProperty("paparazzi.build.dir"), "bitrise-snapshots/$name.png")
+        return object : SnapshotHandler.FrameHandler by frames {
+            override fun handle(image: BufferedImage) {
+                file.parentFile.mkdirs()
+                ImageIO.write(image, "png", file)
+                frames.handle(image)
+            }
+        }
+    }
+}
+```
+
+In your tests, replace `Paparazzi(...)` with `bitrisePaparazzi(...)`. Then add the following to the module's `build.gradle.kts`. The first block lets the handler use `java.awt` on Android Gradle plugin 8, and the second one removes the snapshots of the previous run and keeps the current ones in the build cache:
+
+```kotlin
+tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinJvmCompile>().configureEach {
+    if ("UnitTest" in name) compilerOptions.noJdk.set(false)
+}
+
+tasks.withType<Test>().configureEach {
+    val snapshots = layout.buildDirectory.dir("bitrise-snapshots")
+    outputs.dir(snapshots)
+    doFirst { snapshots.get().asFile.deleteRecursively() }
+}
+```
+
+The example is for Paparazzi 1.3.5. On Paparazzi 2.0, create the report writer with `HtmlReportWriter(maxPercentDifference = maxPercentDifference)`.
+
+</TabItem>
+<TabItem value="roborazzi" label="Roborazzi">
 
 Copy Roborazzi's screenshots under the attachment name after each Roborazzi run:
 
@@ -199,9 +261,7 @@ tasks.named { it == "finalizeTestRoborazziDebug" }.configureEach { finalizedBy(b
 Roborazzi writes screenshots only when you run `recordRoborazziDebug`, `verifyRoborazziDebug`, or `compareRoborazziDebug`. Parameterized tests don't get attachments.
 
 </TabItem>
-<TabItem value="react-native" label="React Native">
-
-**Detox**
+<TabItem value="detox" label="Detox">
 
 Point `artifacts.pathBuilder` in your Detox configuration to this file. It names every screenshot, video, and log the way jest-junit names the test with its default settings:
 
@@ -229,9 +289,7 @@ module.exports = class BitrisePathBuilder {
 ```
 
 </TabItem>
-<TabItem value="web" label="Web">
-
-**Playwright**
+<TabItem value="playwright" label="Playwright">
 
 Turn on `includeProjectInTestName` for the junit reporter, and add a reporter that copies the screenshots and videos of each test under the attachment name:
 

From d08e006518bf68918bd6e3b61c247e34904f3f79 Mon Sep 17 00:00:00 2001
From: AndrasEszes <andras.eszes@bitrise.io>
Date: Tue, 6 Oct 2026 16:44:16 +0200
Subject: [PATCH 4/6] Address review: per-device Espresso labels, per-task
 Paparazzi folders

Two devices on the same API level got the same Espresso screenshot
name, and the Export Step skips duplicate names, so neither was
attached. The label now carries the screen size too, which tells
phone and tablet emulators apart.

Every Test task deleted and refilled one shared bitrise-snapshots
folder, so a later variant's task wiped the snapshots of tests that
only ran in an earlier one. Each task now writes to its own folder,
named through a system property.
---
 .../testing/deploying-and-viewing-test-results.mdx    | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/docs/bitrise-ci/testing/deploying-and-viewing-test-results.mdx b/docs/bitrise-ci/testing/deploying-and-viewing-test-results.mdx
index 1adc5279..a4ed10dc 100644
--- a/docs/bitrise-ci/testing/deploying-and-viewing-test-results.mdx
+++ b/docs/bitrise-ci/testing/deploying-and-viewing-test-results.mdx
@@ -155,6 +155,7 @@ dependencies {
 // app/src/androidTest/java/com/example/testing/BitriseScreenshotListener.kt
 package com.example.testing
 
+import android.content.res.Resources
 import android.os.Build
 import androidx.test.core.app.takeScreenshot
 import androidx.test.core.graphics.writeToTestStorage
@@ -170,7 +171,8 @@ class BitriseScreenshotListener : RunListener() {
     override fun testStarted(test: Description) {
         val default = DefaultFailureHandler(InstrumentationRegistry.getInstrumentation().targetContext)
         Espresso.setFailureHandler { error, viewMatcher ->
-            val name = "${clean(test.className)}__${clean(test.methodName)}__api${Build.VERSION.SDK_INT}_failure"
+            val screen = Resources.getSystem().displayMetrics.run { "${widthPixels}x$heightPixels" }
+            val name = "${clean(test.className)}__${clean(test.methodName)}__api${Build.VERSION.SDK_INT}_${screen}_failure"
             takeScreenshot().writeToTestStorage(name)
             default.handle(error, viewMatcher)
         }
@@ -215,7 +217,7 @@ class BitriseSnapshotHandler(
         val test = snapshot.testName
         val label = snapshot.name?.replace(Regex("_+"), "_")?.removePrefix("_") ?: "snapshot"
         val name = "${clean("${test.packageName}.${test.className}")}__${clean(test.methodName)}__$label"
-        val file = File(System.getProperty("paparazzi.build.dir"), "bitrise-snapshots/$name.png")
+        val file = File(System.getProperty("paparazzi.build.dir"), "bitrise-snapshots/${System.getProperty("bitrise.test.task")}/$name.png")
         return object : SnapshotHandler.FrameHandler by frames {
             override fun handle(image: BufferedImage) {
                 file.parentFile.mkdirs()
@@ -227,7 +229,7 @@ class BitriseSnapshotHandler(
 }
 ```
 
-In your tests, replace `Paparazzi(...)` with `bitrisePaparazzi(...)`. Then add the following to the module's `build.gradle.kts`. The first block lets the handler use `java.awt` on Android Gradle plugin 8, and the second one removes the snapshots of the previous run and keeps the current ones in the build cache:
+In your tests, replace `Paparazzi(...)` with `bitrisePaparazzi(...)`. Then add the following to the module's `build.gradle.kts`. The first block lets the handler use `java.awt` on Android Gradle plugin 8, and the second one gives each test task its own folder, removes the snapshots of the previous run, and keeps the current ones in the build cache:
 
 ```kotlin
 tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinJvmCompile>().configureEach {
@@ -235,7 +237,8 @@ tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinJvmCompile>().configureEa
 }
 
 tasks.withType<Test>().configureEach {
-    val snapshots = layout.buildDirectory.dir("bitrise-snapshots")
+    val snapshots = layout.buildDirectory.dir("bitrise-snapshots/$name")
+    systemProperty("bitrise.test.task", name)
     outputs.dir(snapshots)
     doFirst { snapshots.get().asFile.deleteRecursively() }
 }

From 1a6d2e57b5ca2dfbdb4d36e7f722e1e9800dedf6 Mon Sep 17 00:00:00 2001
From: zoltan-baba <zoltan.baba@bitrise.io>
Date: Wed, 7 Oct 2026 17:49:36 +0200
Subject: [PATCH 5/6] Clarify attachment naming, exporting and troubleshooting

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 .../deploying-and-viewing-test-results.mdx    | 47 ++++++++++++++-----
 1 file changed, 34 insertions(+), 13 deletions(-)

diff --git a/docs/bitrise-ci/testing/deploying-and-viewing-test-results.mdx b/docs/bitrise-ci/testing/deploying-and-viewing-test-results.mdx
index a4ed10dc..efdf1285 100644
--- a/docs/bitrise-ci/testing/deploying-and-viewing-test-results.mdx
+++ b/docs/bitrise-ci/testing/deploying-and-viewing-test-results.mdx
@@ -35,7 +35,7 @@ If you use any of these Steps, make sure you have the **Deploy to Bitrise.io** S
 
 :::important[Attachments and flaky tests]
 
-If your tests generate attachments or you want Bitrise to show flaky tests, the **Deploy to Bitrise.io** Step must be of version 2.19.1 or newer.
+If your tests generate attachments or you want Bitrise to show flaky tests, the **Deploy to Bitrise.io** Step must be of version 2.19.1 or newer. To link attachments to test cases by filename, it must be version 2.26.0 or newer: [Naming attachments after their test case](#naming-attachments-after-their-test-case).
 
 :::
 
@@ -50,7 +50,7 @@ If you run your tests using other Steps (for example, you can use [Script](https
 
    :::important[Attachments and flaky tests]
 
-   If your tests generate attachments or you want Bitrise to show flaky tests, the **Deploy to Bitrise.io** Step must be of version 2.19.1 or newer.
+   If your tests generate attachments or you want Bitrise to show flaky tests, the **Deploy to Bitrise.io** Step must be of version 2.19.1 or newer. To link attachments to test cases by filename, it must be version 2.26.0 or newer: [Naming attachments after their test case](#naming-attachments-after-their-test-case).
 
    :::
 
@@ -92,7 +92,12 @@ Test reports also support the use of the `system-out` tag in JUnit. If a test ca
 
 ## Collating test attachments with test results
 
-Many tests generate image files (screenshot tests, XCUITests, etc). Bitrise test reports automatically collate image files with associated test cases for Xcode tests (using the `xcresult` file).
+Many tests generate image files: screenshot tests, XCUITests, and so on. Bitrise can show these attachments under their associated test cases, so you can view them on the **Tests** tab of your build page. How to collate the test attachments with test results depends on your test tool and whether it generates an `xcresult` file:
+
+- If your tests generate an `xcresult` file, Bitrise automatically collates the attachments with their test cases. This requires no further configuration.
+- If your tests don't generate an `xcresult` file, you can:
+    - Name each file after its test case: [Naming attachments after their test case](#naming-attachments-after-their-test-case).
+    - Reference each file in the JUnit XML: [Referencing attachments in the JUnit XML](#referencing-attachments-in-the-junit-xml).
 
 :::note[Supported file formats]
 
@@ -102,11 +107,6 @@ Currently, we support the following file formats for attachments:
 
 :::
 
-If your tests don't generate an `xcresult` file, Bitrise can still show attachments under their test cases. There are two ways to link them:
-
-- Name each file after its test case: [Naming attachments after their test case](#naming-attachments-after-their-test-case).
-- Reference each file in the JUnit XML: [Referencing attachments in the JUnit XML](#referencing-attachments-in-the-junit-xml).
-
 ### Naming attachments after their test case
 
 Name a screenshot, recording, or log after the test case that produced it, and Bitrise shows it under that test on the **Tests** tab.
@@ -117,15 +117,27 @@ This requires the **Deploy to Bitrise.io** Step version 2.26.0 or newer. If you
 
 :::
 
-The file name has the following structure, for example `com.example.LoginTest__emptyState__1.png`:
+You need to:
+
+- [Use the correct filename structure](#about-the-filename-structure).
+- [Set up your test tool to name the attachments correctly](#setting-up-your-test-tool).
+- [Export the attachments with a Bitrise Step](#exporting-the-attachments).
+
+#### About the filename structure
+
+The filename should have the following structure:
 
 ```text
 <classname>__<name>[__run<k>]__<label>.<ext>
 ```
 
-- Copy `classname` and `name` from the `<testcase>` element of your JUnit XML, and replace any of the `" * / : < > ? \ |` characters with `_`.
+For example, `com.example.LoginTest__emptyState__1.png`.
+
+To get the correct filename:
+
+- Copy `classname` and `name` from the `<testcase>` element of your JUnit XML, and replace any of the `" * / : < > ? \ |` characters with `_`. Bitrise applies the same replacement to the names in the JUnit XML, so either spelling matches.
 - Always add a label, such as a counter. The label can't contain `__` or start with `_`.
-- If the same tests run on more than one device, put the device in the label, for example `api34_1`. Otherwise, the files overwrite each other.
+- If the same tests run on more than one device, put the device in the label, for example `api34_1`. Otherwise, files with the same name are skipped, and the attachments don't appear.
 - To attach a file to a later run of the same test case, add `__run2`, `__run3`, and so on before the label.
 
 #### Setting up your test tool
@@ -334,13 +346,22 @@ export default class BitriseAttachments implements Reporter {
 
 #### Exporting the attachments
 
-If you use the **Export test results to Test Reports** Step, set its **Test result base path** input to a folder that contains both your test results and your attachments, for example `app/build/`. See [Using the Export test results to Test Reports Step](#using-the-export-test-results-to-test-reports-step).
+:::important[Step versions]
+
+This requires the **Deploy to Bitrise.io** Step version 2.26.0 or newer. If you use the **Export test results to Test Reports** Step, it must be version 1.3.0 or newer.
+
+:::
+
+Export the correctly named attachments with Bitrise Steps. You can use:
+
+- The **Deploy to Bitrise.io** Step. It automatically exports test results from certain Steps. For the list, see [Deploying results from the official Bitrise testing Steps](#deploying-results-from-the-official-bitrise-testing-steps).
+- The **Export test results to Test Reports** Step. Set its **Test result base path** input to a folder that contains both your test results and your attachments, for example `app/build/`. See [Using the Export test results to Test Reports Step](#using-the-export-test-results-to-test-reports-step).
 
 #### Troubleshooting missing attachments
 
 If an attachment doesn't show up, check the build log:
 
-- The **Export test results to Test Reports** Step skips files that don't match a test case without a warning. To list them, set its **Enable verbose logging?** input to `yes`.
+- The **Export test results to Test Reports** Step logs a warning for names that match more than one test or file, or that have an invalid `__run` number or no label. Other skipped files appear only with verbose logging: set its **Enable verbose logging?** input to `yes`.
 - The **Deploy to Bitrise.io** Step logs a warning for every file in the report that it can't link to a test case.
 
 ### Referencing attachments in the JUnit XML

From b2063d333a37004f7cd658ce15f90c5cea40376f Mon Sep 17 00:00:00 2001
From: zoltan-baba <zoltan.baba@bitrise.io>
Date: Thu, 8 Oct 2026 11:34:14 +0200
Subject: [PATCH 6/6] Clarify which Steps export attachments

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 .../testing/deploying-and-viewing-test-results.mdx          | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/bitrise-ci/testing/deploying-and-viewing-test-results.mdx b/docs/bitrise-ci/testing/deploying-and-viewing-test-results.mdx
index efdf1285..b6f5fa44 100644
--- a/docs/bitrise-ci/testing/deploying-and-viewing-test-results.mdx
+++ b/docs/bitrise-ci/testing/deploying-and-viewing-test-results.mdx
@@ -352,10 +352,10 @@ This requires the **Deploy to Bitrise.io** Step version 2.26.0 or newer. If you
 
 :::
 
-Export the correctly named attachments with Bitrise Steps. You can use:
+The **Deploy to Bitrise.io** Step is always required: it deploys the correctly named attachments alongside your test results. What else you need depends on the Step that runs your tests:
 
-- The **Deploy to Bitrise.io** Step. It automatically exports test results from certain Steps. For the list, see [Deploying results from the official Bitrise testing Steps](#deploying-results-from-the-official-bitrise-testing-steps).
-- The **Export test results to Test Reports** Step. Set its **Test result base path** input to a folder that contains both your test results and your attachments, for example `app/build/`. See [Using the Export test results to Test Reports Step](#using-the-export-test-results-to-test-reports-step).
+- **Official Bitrise testing Steps**: No further configuration is needed. The **Deploy to Bitrise.io** Step exports the attachments together with the test results. For the list of Steps, see [Deploying results from the official Bitrise testing Steps](#deploying-results-from-the-official-bitrise-testing-steps).
+- **Other Steps**, such as Script or npm Steps: Add the **Export test results to Test Reports** Step after the Step that runs your tests. It finds the attachments and moves them to the location the **Deploy to Bitrise.io** Step deploys from. Set its **Test result base path** input to a folder that contains both your test results and your attachments, for example `app/build/`. See [Using the Export test results to Test Reports Step](#using-the-export-test-results-to-test-reports-step).
 
 #### Troubleshooting missing attachments