docs(en): merge docs-cn/sync-docs into docs-cn/dev @ 14077ca9

api/advanced/artifacts.md

@@ -78,7 +78,7 @@ If your custom artifact narrows the `attachments` type (e.g. to a tuple), includ
 export interface TestAttachment {
   /** MIME type of the attachment (e.g., 'image/png', 'text/plain') */
   contentType?: string
-  /** File system path to the attachment */
+  /** Local file path or external HTTP(S) URL to the attachment. Relative paths are resolved from the project root. */
   path?: string
   /** Inline attachment content as a string or raw binary data */
   body?: string | Uint8Array
@@ -94,7 +94,9 @@ export interface TestAttachment {
 
 The `TestAttachment` interface represents a file or data attachment associated with a test artifact.
 
-Attachments can be either file-based (via `path`) or inline content (via `body`). The `contentType` helps consumers understand how to interpret the attachment data.
+Attachments can be either path-based (via `path`) or inline content (via `body`). The `contentType` helps consumers understand how to interpret the attachment data.
+
+Attachment `path` can point to a local file or an external `http`/`https` URL. Relative local paths are resolved from the project root. Local files are copied into Vitest's attachments directory before reporters receive them. External URLs are preserved as-is.
 
 If you pass a string `body`, Vitest assumes it is already base64-encoded unless you set `bodyEncoding: 'utf-8'`. When you pass `body` as a `Uint8Array`, Vitest automatically encodes it as base64. The `bodyEncoding` option only applies to inline `body` attachments, not `path` attachments.
 

guide/reporters.md

@@ -535,6 +535,29 @@ export default defineConfig({
 })
 ```
 
+:::
+<!-- TODO: translation -->
+Set `singleFile` to generate a self-contained HTML report:
+
+```ts [vitest.config.ts]
+export default defineConfig({
+  test: {
+    reporters: [
+      ['html', { singleFile: true }],
+    ],
+  },
+})
+```
+
+When `singleFile` is enabled, Vitest inlines the UI assets, metadata, and test attachments into a single self-contained `index.html`. This makes the report easy to share, upload, or download as one artifact instead of preserving the whole `html` output directory.
+
+::: warning
+`singleFile` has two caveats:
+
+- The file can grow very large because everything is embedded inline — slow to open, memory-hungry, and possibly over the size limits of artifact viewers or static hosts.
+- Coverage HTML reports are not inlined yet and remain as separate files.
+
+Prefer the default multi-file report when the suite has many or large attachments, or when you need coverage included in the bundle.
 :::
 
 ::: tip

guide/ui.md

@@ -52,12 +52,14 @@ npx vite preview --outDir ./html
 
 你可以使用 [`outputFile`](/config/outputfile) 配置选项配置输出。你需要在那里指定 `.html` 路径。例如，`./html/index.html` 是默认值。
 :::
+<!-- TODO: translation -->
+If you need a portable report that can be opened or shared as one file, see [`singleFile`](/guide/reporters#html-reporter) in the HTML reporter documentation.
 
 ::: tip
 要在持续集成环境，例如 GitHub Actions 中查看 HTML 报告，请将输出目录作为产物上传：
 
 ```yaml
-- uses: actions/upload-artifact@v4
+- uses: actions/upload-artifact@v7
   id: upload-report
   with:
     name: vitest-report
@@ -68,6 +70,15 @@ npx vite preview --outDir ./html
 ```
 
 这会在任务摘要中添加一个链接。点击该链接即可在浏览器中直接通过 [Vitest Viewer](https://viewer.vitest.dev/) 查看报告。你也可以手动下载产物并解压，然后按照前文所述在本地运行 `vite preview` 命令。
+<!-- TODO: translation -->
+When you use `singleFile: true`, you can upload the report as a single file and it will become viewable directly GitHub artifacts with `archive: false` option:
+
+```yaml
+- uses: actions/upload-artifact@v7
+  with:
+    path: html/index.html
+    archive: false
+```
 :::
 
 ## 模块图 {#module-graph}