Merge pull request #974 from vitest-dev/sync-ea5391c0-1

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

Author: NoiseFan

api/browser/commands.md

@@ -125,6 +125,25 @@ declare module 'vitest/browser' {
 ::: warning
 如果自定义命令具有相同的名称，则它们将覆盖内置命令。
 :::
+<!-- TODO: translation -->
+### Recording trace markers
+
+Custom commands can record [trace markers](/api/browser/context#mark) for the test that triggered them through `context.mark`. This is the server-side equivalent of `page.mark` and helps annotate the [trace view](/guide/browser/trace-view) with custom actions performed inside a command.
+
+```ts
+import type { BrowserCommand } from 'vitest/node'
+
+export const uploadFixture: BrowserCommand<[name: string]> = async (
+  context,
+  name,
+) => {
+  await context.mark(`upload start: ${name}`, { kind: 'action' })
+  // ... do server-side work
+  await context.mark(`upload done: ${name}`, { kind: 'action' })
+}
+```
+
+`context.mark` is a no-op when browser tracing is not enabled or no test is currently running in the session. Unlike `page.mark`, it does not accept a callback form.
 
 ### 自定义 `playwright` 命令  {#custom-playwright-commands}
 

api/browser/context.md

@@ -122,7 +122,7 @@ export const page: {
 请注意，如果 `save` 设置为 `false`，`screenshot` 将始终返回 base64 字符串。
 在这种情况下，`path` 也会被忽略。
 :::
-
+<!-- TODO: translation -->
 ### mark
 
 ```ts
@@ -157,6 +157,8 @@ await page.mark('submit flow', async () => {
 
 ::: tip
 This method is useful only when [`browser.trace`](/config/browser/trace) is enabled.
+
+A server-side equivalent is available on the [`BrowserCommandContext`](/api/browser/commands#recording-trace-markers) so [custom commands](/api/browser/commands#custom-commands) can record markers attributed to the test that triggered them.
 :::
 
 ### frameLocator

config/attachmentsdir.md

@@ -3,9 +3,11 @@ title: attachmentsDir | 配置
 outline: deep
 ---
 
-# attachmentsDir
+# attachmentsDir <CRoot />
 
 - **类型:** `string`
 - **默认值:** `'.vitest/attachments'`
 
-用于存储 [`context.annotate`](/guide/test-context#annotate) 所创建附件的目录路径（相对于项目根目录）。
+Directory path for storing file attachments created by [`context.annotate`](/guide/test-context#annotate).
+
+This option is resolved relative to the root Vitest config. When using [`projects`](/guide/projects), all projects share the same `attachmentsDir`; it cannot be configured per project.

guide/browser/trace-view.md

@@ -101,7 +101,7 @@ Trace entries are recorded automatically for:
 
 Each entry captures the DOM state at that point, along with timing information, the selector, and the source location that triggered it.
 
-Element highlighting is best-effort. Some provider-specific selectors, shadow DOM selectors, or elements that are not present in the captured snapshot may not be highlighted.
+In Vitest UI, trace entries are streamed as the test runs, so you can inspect recorded steps before the test finishes. Long-running actions, `expect.element(...)` assertions, and callback `page.mark()` entries appear as in-progress steps first, then update with their final status and duration.
 
 ## Custom Trace Entries
 

guide/projects.md

@@ -285,10 +285,11 @@ export default defineConfig({
 
 ::: danger 不支持的选项
 部分配置选项不允许在项目配置中使用，主要包括：
-
+<!-- TODO: translation -->
 - `coverage`：覆盖率统计针对整个进程
 - `reporters`：只支持根级别的 reporters
 - `resolveSnapshotPath`：只尊重根级别的快照路径解析器
+- `attachmentsDir`: attachments are stored in one root-level directory shared by all projects
 - 其他不影响测试运行器的选项
 
 所有不支持在项目配置中使用的配置选项，在 ["配置"](/config/) 指南中会用 <CRoot /> 标记。它们必须在根配置文件中定义一次。