# @avalix/chroma 中文文档

规范地址：https://npmcn.com/package/%40avalix/chroma/

版本：1\.2\.0
npm 元数据更新时间：2026-07-09T02:22:57.953Z
中文译文更新时间：2026-11-07T07:36:44.686Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40avalix/chroma
原文对照：https://npmcn.com/package/%40avalix/chroma/?lang=original
项目主页：https://chroma.avalix.dev/docs
源码仓库：https://github.com/avalix-labs/chroma

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

- 包体积（解压后）：418 kB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：1 个
- peer 依赖：@playwright/test ^1\.61\.1
- 首次发布：2025-09-14T15:01:58.586Z
- 最新版本发布：2026-07-09T02:22:57.806Z
- 近 30 天下载量：6486（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 12 个）

## 中文简介

用于 Polkadot, Ethereum 和 Solana 钱包交互的端到端测试库

## 安装

```sh
npm install @avalix/chroma
```

也可以使用：`pnpm add @avalix/chroma`、`yarn add @avalix/chroma`、`bun add @avalix/chroma`

## README

# @avalix/克罗玛

Polkadot, Ethereum 的端到端测试库,以及使用 Playwright 的索拉纳钱包交互.

## 文档

我们强烈建议你看看 [色相文档](https://chroma.avalix.dev/docs) 升级到平面。 它是一个很好的资源,可以更多地了解图书馆. 它涵盖了从开始到CI/CD集成和多克设置等高级主题的一切.

## 安装

```bash
npm install @avalix/chroma @playwright/test
```

**说明**数字 : `@playwright/test` 是一种同伴依赖,必须单独安装以避免冲突.

### 下载扩展

在运行测试前, 您需要下载钱包扩展名 :

```bash
npx chroma download-extensions
```

这将下载钱包扩展名(例如MetaMask、Polkadot JS、Talisman)至 `./.chroma` 在您的工程根中设置目录.

**提示**: 将此添加到您的 `package.json` 方便用的脚本 :

```json
{
  "scripts": {
    "test:prepare": "chroma download-extensions"
  }
}
```

**重要**:您必须在运行 Playwright 测试前运行此命令 。 如果找不到扩展名, 测试会因有帮助的错误消息而失败 .

## 快速启动

```typescript
import { createWalletTest, expect } from '@avalix/chroma'

const test = createWalletTest({
  wallets: [{ type: 'metamask' }]
})

test('connect wallet and sign transaction', async ({ page, wallets }) => {
  const metamask = wallets.metamask

  await metamask.importSeedPhrase({
    seedPhrase: 'test test test test test test test test test test test junk'
  })

  await page.goto('http://localhost:3000')
  await page.click('button:has-text("Connect Wallet")')
  await metamask.approve()

  await page.click('button:has-text("Send Transaction")')
  await metamask.approve()

  await expect(page.locator('.transaction-success')).toBeVisible()
})
```

### 多个钱包

```typescript
import { createWalletTest } from '@avalix/chroma'

const test = createWalletTest({
  wallets: [{ type: 'metamask' }, { type: 'talisman' }]
})

test('multi-wallet test', async ({ page, wallets }) => {
  const metamask = wallets.metamask
  const talisman = wallets.talisman

  await metamask.importSeedPhrase({ seedPhrase: 'test test test test test test test test test test test junk' })
  await talisman.importEthPrivateKey({ privateKey: '0x...', name: 'Bob' })

  await page.goto('http://localhost:3000')
  await metamask.approve()
})
```

### 设置工程模式

默认情况下,浏览器上下文使用临时配置,所以钱包状态(导入的账户,密码)在运行间丢失. 导入种子短语 **一次** 并重新使用所有规格的制备状态,结合 `userDataDir` 财务报告和审定财务报表 `cloneUserDataDirFrom` 选项 [Playwright 的设置项目模式](https://playwright.dev/docs/test-global-setup-teardown)。 。 。 .

设置项目将准备的配置文件写入共享目录; spec 工程然后指向 a `userDataDir` 或复制它为平行.

#### 1\. 设置项目——种子一次

装有监视器文件的测试卫士 `playwright test` 并没有尝试登入一个已经准备好的配置文件(第二次运行将会在不再符合导入流量的UI上陷入僵局). 删除 `.cache/wallet-setup` 以迫使一个新的种子.

```typescript
// metamask.setup.ts
import fs from 'node:fs'
import path from 'node:path'
import { createWalletTest } from '@avalix/chroma'

const SETUP_DIR = '.cache/wallet-setup'
const SENTINEL = path.join(SETUP_DIR, '.chroma-onboarded')

const setup = createWalletTest({
  wallets: [{ type: 'metamask' }],
  userDataDir: SETUP_DIR,
})

setup('seed metamask', async ({ wallets }) => {
  if (fs.existsSync(SENTINEL))
    return

  await wallets.metamask.importSeedPhrase({
    seedPhrase: 'test test test test test test test test test test test junk',
  })
  fs.writeFileSync(SENTINEL, '')
})
```

#### 2\. 共享的光谱固定装置

Spec 文件导入共享 `test` 工厂指出已准备好的简介。 因为MetaMask靴子在先前上载的配置文件上进入了锁定状态,所以每个光谱必须调用 `wallets.metamask.unlock()` 一次(这是一分之一的——当MetaMask已经解锁时,这个呼叫是没有的). 在解锁时,MetaMask侧面板会为测试会话的其余部分打开.

```typescript
// fixtures.ts — shared by your spec files
import { createWalletTest } from '@avalix/chroma'

export const test = createWalletTest({
  wallets: [{ type: 'metamask' }],
  userDataDir: '.cache/wallet-setup',
})

export { expect } from '@playwright/test'
```

```typescript
// some.spec.ts
import { test } from './fixtures'

test('connect and sign', async ({ page, wallets }) => {
  const metamask = wallets.metamask

  await page.goto('http://localhost:3000')
  await metamask.unlock()

  await page.click('button:has-text("Connect Wallet")')
  await metamask.approve()

  await page.click('button:has-text("Sign Message")')
  await metamask.approve()
})
```

#### 3\. 连接项目

```typescript
// playwright.config.ts
export default defineConfig({
  workers: 1,
  projects: [
    { name: 'setup', testMatch: /.*\.setup\.ts/ },
    {
      name: 'metamask',
      testMatch: /.*\.spec\.ts/,
      dependencies: ['setup'],
    },
  ],
})
```

#### 平行工人(高级)

色调锁 `userDataDir`,所以多个工人不能同时共享同一路径. 使用 `cloneUserDataDirFrom` 加上每个工人 `userDataDir` 向每个工人提供自己编制的简介:

```typescript
export const test = createWalletTest({
  wallets: [{ type: 'metamask' }],
  userDataDir: ({ workerIndex }) => `.cache/wallet-w${workerIndex}`,
  cloneUserDataDirFrom: '.cache/wallet-setup',
})
```

设定 `workers: undefined` (或更高)在你的项目中验证了平行运行——克隆剖面图之间的相互作用,MetaMask的锁定状态恢复,而Playwright的侧面板探测仍然被硬化.

## 特征

-   **简单扩展设置** - 以单一命令下载钱包扩展名
-   **多钱包支持** - 测试同时使用多个钱包扩展
-   **类型脚本支持** - 全面安全和自动完成
-   **VS 代码整合** - 与 [VS 代码的 playwright 测试](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright)

## 所需资源

-   节点.js 24+
-   @playwright/test ^1.55.0 (英语)

## 许可证

麻省理工学院

## 常见问题

### @avalix/chroma 是什么？

用于 Polkadot, Ethereum 和 Solana 钱包交互的端到端测试库

### 如何安装 @avalix/chroma？

在项目目录运行 npm install @avalix/chroma，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@playwright/test（^1\.61\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 chroma，可以用 npx chroma 直接运行。

### @avalix/chroma 支持 TypeScript 吗？

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

### @avalix/chroma 支持 ESM 还是 CommonJS？

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

### @avalix/chroma 需要什么版本的 Node\.js？

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

### @avalix/chroma 可以商用吗？

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

### @avalix/chroma 的下载量有多少？

根据 npm 官方下载统计，@avalix/chroma 在 2026/10/07 – 2026/11/05 这 30 天内被下载 6,486 次，日均约 216 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @avalix/chroma 还在维护吗？

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