# @friendsofshopware/vitest-shopware-admin-bridge 中文文档

规范地址：https://npmcn.com/package/%40friendsofshopware/vitest-shopware-admin-bridge/

版本：0\.2\.1
npm 元数据更新时间：2026-09-06T16:50:17.392Z
中文译文更新时间：2026-11-15T14:17:04.105Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40friendsofshopware/vitest-shopware-admin-bridge
原文对照：https://npmcn.com/package/%40friendsofshopware/vitest-shopware-admin-bridge/?lang=original
项目主页：https://github.com/FriendsOfShopware/vitest-shopware-admin-bridge#readme
源码仓库：https://github.com/FriendsOfShopware/vitest-shopware-admin-bridge

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：169 kB，42 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^22\.12\.0 \|\| ^24\.0\.0 \|\| \>=26\.0\.0
- 运行依赖：7 个
- peer 依赖：vite ^6\.4\.0 \|\| ^7\.0\.0 \|\| ^8\.0\.0，vitest ^5\.0\.0
- 首次发布：2026-08-26T06:24:57.015Z
- 最新版本发布：2026-09-06T16:50:17.076Z
- 近 30 天下载量：3534（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

商店软件6的Vitest桥

## 安装

```sh
npm install @friendsofshopware/vitest-shopware-admin-bridge
```

也可以使用：`pnpm add @friendsofshopware/vitest-shopware-admin-bridge`、`yarn add @friendsofshopware/vitest-shopware-admin-bridge`、`bun add @friendsofshopware/vitest-shopware-admin-bridge`

## README

# 虚拟商店软件管理桥

`@friendsofshopware/vitest-shopware-admin-bridge` 提供 Vitest 和 Vue 测试 商店软件6管理扩展的Utils环境. 它真的穿了靴子 行政运行时间,同时保留版本敏感设置 每个扩展名.

该桥目前支持商店软件6.6和6.7. 它还探测和使用 本地商店软件设置- SFC 当更新的行政管理源树时转换 把它装上船.

## 文档

-   [设置新商店软件插件](https://npmcn.com/package/%40friendsofshopware/vitest-shopware-admin-bridge/docs/getting-started.md) 覆盖本地文件 布局、第一次测试、npm锁文件、一个商店软件版 CI矩阵和一个 可选的释放艺术工作.
-   [测试最佳做法](https://npmcn.com/package/%40friendsofshopware/vitest-shopware-admin-bridge/docs/best-practices.md) 解释测试的级别 选择、 如何隔离 Shopware 状态以及哪些助手属于 而不是桥.
-   [库存用品测试](https://npmcn.com/package/%40friendsofshopware/vitest-shopware-admin-bridge/docs/testing-inventory.md) 记录上游 测试模式和桥的相容性边界.

## 所需资源

-   6.6或6.7 商店软件 管理源和已安装 npm 依赖
-   节点:22.12+、24或26+
-   npm 10+ (韩语)
-   维特5和维特6.4+

桥在Shopware monorepo,作曲家中发现了一个行政部门 安装,或 npm `administration` 链接. `SHOPWARE_ADMINISTRATION_PATH` 遗产 `ADMIN_PATH` 可以覆盖发现。 发现只读: 桥从不下载或修改商店软件.

## 快开始

安装已公布的软件包并输入由此生成的 npm 锁文件 。 见 [完整的插件设置指南](https://npmcn.com/package/%40friendsofshopware/vitest-shopware-admin-bridge/docs/getting-started.md) 行政费 依赖性安装和CI:

```bash
npm install --save-dev vitest@5 @friendsofshopware/vitest-shopware-admin-bridge
```

```ts
// vitest.config.ts
import { defineShopwareConfig } from '@friendsofshopware/vitest-shopware-admin-bridge';

export default defineShopwareConfig();
```

```json
{
    "scripts": {
        "test:unit": "vitest run",
        "test:unit:watch": "vitest"
    }
}
```

试验在下列条件下发现: `src/` 财务报告和审定财务报表 `test/` 使用 `.spec.*` 或者说 `.test.*`。 。 。 . 消费者选择权被合并,而不允许强制的jsdom 靴子套 替换:

```ts
export default defineShopwareConfig({
    administrationPath: process.env.SHOPWARE_ADMINISTRATION_PATH,
    runtime: {
        strictConsole: true,
    },
    vitest: {
        test: {
            include: ['tests/unit/**/*.spec.ts'],
        },
    },
});
```

配置安装 :

-   正确的6.6 Vue相容性或6.7 原生 Vue 运行时间;
-   (一) 现有行政内设机构;
-   Twig、SCSS/CSS/Less和SVG处理;
-   真正的商店软件组件、混合、指令、过滤器、状态和服务登记;
-   pinia行政当局在6.7上存放起首器和上下文,并在6.6上存放一个安全不开放的通知店,以及遗留的Vuex状态;
-   每一次测试都有新鲜的皮尼亚和遗留的Vuex状态;
-   Vue Test Utils 插件,依赖性注射,同步本地/i18n和标准管理模拟.

全程还安装了用于常见布局的档位保留根 (单位:千美元)`sw-page`, (中文(简体) ), `sw-card-view`, (中文(简体) ), `mt-card`, (中文(简体) ), `mt-banner`, (中文(简体) ), `mt-empty-state`, (中文(简体) ), `mt-link` 财务报告和审定财务报表 `sw-search-bar`)外加轻量级图标根. 名称 `sw-page` 因此,内容和智能栏插槽仍然可见,没有 本地页面站地图.

## 组件测试

导入扩展切入点以注册其组件,然后挂载 商店软件组件名称 :

```ts
import { expect, it } from 'vitest';
import { mountShopwareComponent } from '@friendsofshopware/vitest-shopware-admin-bridge/test-utils';
import '../src/main';

it('renders the widget', async () => {
    const wrapper = await mountShopwareComponent('acme-widget', {
        props: { title: 'Orders' },
    });

    expect(wrapper.text()).toContain('Orders');
});
```

`loadShopwareComponent()` 扫描已安装的行政管理源,不用 写入 Shopware 的私有生成组件映射 。 允许扩展至 测试覆盖和扩展核心组件,即使其基础组件是 尚未登记。 依存在连续加载之前 `Shopware.Component.build()` 应用覆盖链.

生成的导入图被缓存于操作系统的临时 (原始内容存档于2017-09-25). Directory per Administration Git 修订版. 编辑时禁用缓存 选定行政源而不改变其修订:

```ts
export default defineShopwareConfig({
    runtime: { componentScanCache: false },
});
```

`VITEST_SHOPWARE_ADMIN_BRIDGE_CACHE_DIR` 可将缓存置于不同的下方 基础目录。 缓存读取和写出故障会回到新的扫描中.

```ts
Shopware.Component.override('sw-button', overrideConfig);
await loadShopwareComponent('sw-button');
const component = await buildShopwareComponent('sw-button');
```

可用组件公用事业:

-   `loadShopwareComponent(name)`
-   `buildShopwareComponent(name)`
-   `mountShopwareComponent(name, options)`
-   `shallowMountShopwareComponent(name, options)`
-   直接 Vue 测试 Utils 导出 : `mount`, (中文(简体) ), `shallowMount`, (中文(简体) ), `flushPromises`, (中文(简体) ), `config`

## 服务、ACL和专题旗帜

默认服务模拟每次测试前重置. ACL允许默认访问, 特性标记不活动,用户配置为空,寄存器调用 返回空结果.

```ts
import {
    getShopwareTestServices,
    mockShopwareService,
    setAclRoles,
    setFeatureFlags,
    withShopwareService,
} from '@friendsofshopware/vitest-shopware-admin-bridge/test-utils';

setAclRoles(['order.viewer']);
setFeatureFlags(['FEATURE_NEXT']);

const restore = mockShopwareService('myService', { load: vi.fn() });
restore();

await withShopwareService('myService', replacement, async () => {
    // Shopware.Service('myService') and inject('myService') use replacement.
});

getShopwareTestServices().userConfigService.search.mockResolvedValue({ data: {} });
```

范围化服务助手更新 Shopware 的瓶装容器和 Vue 依赖性注射,然后恢复之前的确切实例。 任何未修复的 测试后自动清理范围.

## 仓库双倍

该桥提供小型的DAL形双人,而不是Shopware的私人 HTTP/实体-测试基础设施:

```ts
const products = createRepositoryMock({
    search: vi.fn().mockResolvedValue({
        data: [{ id: 'product-1' }],
        total: 1,
    }),
});

setRepositoryMocks({ product: products });
```

未配置的实体名称会立即丢出, 而不是默默返回 错误的固定.

## 二. 背景和状况

`setShopwareContext()` 更新 `Shopware.Context.api` 真实的 上下文/会话/系统存储。 Pinia商店使用的桥靴 6.7商店和Vuex商店在6.6商店工作:

```ts
setShopwareContext({
    api: { languageId: 'language-id' },
    session: { locale: 'de-DE', locales: ['de-DE'], languageId: 'language-id' },
});
```

标准 `en-GB` 财务报告和审定财务报表 `de-DE` 在扩展代码前注册了地方 运行。 通过 Shopware 的本地化工厂添加的本地化消息是同步的 之前的 Vue i18n 实例 `mountShopwareComponent()` 财务报告和审定财务报表 `shallowMountShopwareComponent()` 挂载组件 .

状态自动重设 . `resetShopwareTestState()` 当 单一测试需要返回默认的 API 上下文、 本地状态、 服务 和新鲜的皮尼亚明确.

## 运行时间

Class, API 客户端和其他非组件测试可以使用更轻的运行时间 保留商店软件上下文、 状态和服务助手但跳过管理 组件发现、组合、指令、过滤器和组件辅助器 登记:

```ts
export default defineShopwareConfig({
    runtime: { mode: 'lite' },
    vitest: {
        test: { include: ['test/core/**/*.spec.ts'] },
    },
});
```

当一个软件包需要两种模式时,使用单独的Vitest配置. 测试 挂载注册的商店软件组件必须继续使用默认 `mode: 'full'` 运行时间.

## Vue 包装查询和气象器交互

桥将这些方法安装在每个 Vue 包装上,并导出为 独立函数 :

-   `findByText(selector, text)`
-   `findByAriaLabel(selector, text)`
-   `findByLabel(text)`
-   `findByPlaceholder(text)`

`selectMtSelectOptionByText(wrapper, text)` 覆盖反复出现的气象器选择 交互,同时接受遗留的弹出或基于角色的选项 标记.

## 严格控制台模式

启用 `runtime.strictConsole` 无法进行出乎意料的测试 `console.warn` 或者说 `console.error`允许在测试中故意输出 拥有:

```ts
allowConsoleMessage('expected deprecation', 'warn');
```

严格模式开始于 Shopware 拖带之后, 因此它报告测试行为 而不是初始化的噪音.

## 兼容合同

该桥有意将稳定的测试适配器与 Shopware 运行时分离 行为.

桥梁自有的适配器对每个受支持的行政部门的行为相同:

-   Twig 和导入的 HTML 成为 HTML 字符串; HTML 和 Twig 注释被删除 保存所有其他字节;
-   SVG 的导入包含精确的 UTF-8 文件内容 ;
-   CSS、SCSS和Less进口在单位测试中确定为空模块;
-   jsdom 多填充,寄存器双倍,查询和控制台执行使用 bridge自己的版本合同.

选定的行政部门对Vue或Vue Compat仍具有权威性, 商店的部件 和Twig运行时间工厂, 国家,服务,混合, 指令、过滤器、核心组件和本地设置-SFC转换。 这个 保持测试的API稳定,不做商店软件6.6测试 复制了 6.7 运行时的行为。 桥上没有进口商店软件的私人Twig, SVG或风格为Vite插件.

## 诊断

```bash
npx vitest-shopware-admin-bridge doctor
npx vitest-shopware-admin-bridge doctor --json
npx vitest-shopware-admin-bridge doctor --admin-path /path/to/administration
```

如果缺少依赖关系, 命令会打印精确 `npm ci --prefix ...` 命令。 它不会自动运行命令 .

## 设计边界和相容性证据

见 [文件/测试-库存](https://npmcn.com/package/%40friendsofshopware/vitest-shopware-admin-bridge/docs/testing-inventory.md) 用于商店软件测试 模式库存、帮助者所有权决定、缺口关闭表和可执行文件 证明每个兼容行为.

## 常见问题

### @friendsofshopware/vitest-shopware-admin-bridge 是什么？

商店软件6的Vitest桥

### 如何安装 @friendsofshopware/vitest-shopware-admin-bridge？

在项目目录运行 npm install @friendsofshopware/vitest-shopware-admin-bridge，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vite（^6\.4\.0 \|\| ^7\.0\.0 \|\| ^8\.0\.0）、vitest（^5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 vitest-shopware-admin-bridge，可以用 npx vitest-shopware-admin-bridge 直接运行。

### @friendsofshopware/vitest-shopware-admin-bridge 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @friendsofshopware/vitest-shopware-admin-bridge 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @friendsofshopware/vitest-shopware-admin-bridge 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^22\.12\.0 \|\| ^24\.0\.0 \|\| \>=26\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @friendsofshopware/vitest-shopware-admin-bridge 可以商用吗？

@friendsofshopware/vitest-shopware-admin-bridge 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @friendsofshopware/vitest-shopware-admin-bridge 的下载量有多少？

根据 npm 官方下载统计，@friendsofshopware/vitest-shopware-admin-bridge 在 2026/10/16 – 2026/11/14 这 30 天内被下载 3,534 次，日均约 118 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @friendsofshopware/vitest-shopware-admin-bridge 还在维护吗？

最新版本 0\.2\.1 发布于 2026/09/07（2 个月前）；至今共发布 5 个版本，其中过去 12 个月发布了 5 个；首次发布于 2026/08/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。