# @beeman/testcontainers 中文文档

规范地址：https://npmcn.com/package/%40beeman/testcontainers/

版本：1\.2\.3
npm 元数据更新时间：2026-05-24T19:47:47.427Z
中文译文更新时间：2026-11-07T20:50:22.856Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40beeman/testcontainers
原文对照：https://npmcn.com/package/%40beeman/testcontainers/?lang=original
项目主页：https://github.com/beeman/testcontainers#readme
源码仓库：https://github.com/beeman/testcontainers

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

- 包体积（解压后）：67.8 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@solana/kit ^6，@solana/kit-plugins ^0\.3，testcontainers ^11 \|\| ^12，typescript ^5 \|\| ^6
- 首次发布：2026-01-23T13:59:21.905Z
- 最新版本发布：2026-05-24T19:47:47.157Z
- 近 30 天下载量：2633（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 18 个）

## 中文简介

收集资料 [测试容器](https://testcontainers.com/) 用真实服务测试您的应用程序.

## 安装

```sh
npm install @beeman/testcontainers
```

也可以使用：`pnpm add @beeman/testcontainers`、`yarn add @beeman/testcontainers`、`bun add @beeman/testcontainers`

## README

# @ beeman/ 测试容器

收集资料 [测试容器](https://testcontainers.com/) 用真实服务测试您的应用程序.

## 安装

安装软件包和测试容器 :

```bash
bun add @beeman/testcontainers testcontainers
```

## 可用集装箱

### LibSQL 服务器

这个 `LibsqlServerContainer` 提供在 Docker 容器中运行的 libSQL 服务器 。 它使用 `ghcr.io/beeman/libsql-server-healthcheck` 默认的图像可以让 Testcontainers 等待容器健康检查而不是日志输出 .

#### 使用量

如果您想要使用下面的示例客户端, 请同时安装 `@libsql/client`数字 :

```bash
bun add @libsql/client
```

```typescript
import { createClient } from '@libsql/client'
import { LibsqlServerContainer } from '@beeman/testcontainers'

const container = await new LibsqlServerContainer().start()
const client = createClient({ url: container.url })

await client.execute('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL)')
await client.execute({
  sql: 'INSERT INTO users(name) VALUES (?)',
  args: ['beeman'],
})

const result = await client.execute('SELECT id, name FROM users')

console.log(result.rows[0]?.name)

client.close()
await container.stop()
```

#### 属性

-   `container.url`: 返回 HTTP URL(例如, `http://localhost:32768`) (中文(简体) ).
-   `container.urlGrpc`: 返回 gRPC URL(例如, `http://localhost:32769`) (中文(简体) ).
-   `container.port`: 返回映射的 HTTP 端口.
-   `container.portGrpc`: 返回已映射的 gRPC 端口.

对于高级的libSQL配置,如认证、复制或持续存储,使用所继承的 `GenericContainer` 来自测试容器的方法.

### 索拉纳测试验证器

这个 `SolanaTestValidatorContainer` 提供真实的索拉纳验证器在多克容器中运行,适合集成测试. 它使用 `beeman/solana-test-validator` 默认图像.

#### 使用量

如果你想用这个 `createLocalSolanaClient` 下面的帮助,请参见可选安装 `createLocalSolanaClient` 节.

```typescript
import { SolanaTestValidatorContainer, createLocalSolanaClient } from '@beeman/testcontainers'

// Start the container
const container = await new SolanaTestValidatorContainer().start()

// Create a client with auto-generated payer
const client = await createLocalSolanaClient({ container })

// ... run your tests ...

// Stop the container when done
await container.stop()
```

#### 属性

-   `container.url`: 返回 RPC URL(例如, `http://localhost:32768`) (中文(简体) ).
-   `container.urlWs`: 返回 WebSocket URL(例如, `ws://localhost:32769`) (中文(简体) ).
-   `container.port`: 返回映射的 RPC 端口.
-   `container.portWs`: 返回已映射的 WebSocket 端口.

### 冲浪池

这个 `SurfpoolContainer` 页:1 [冲浪池](https://github.com/txtx/surfpool) 索拉纳模拟器在一个多克容器中运行. 它默认以离线模式运行,用于孤立测试. 它使用 `surfpool/surfpool:latest` 默认图像.

#### 基本用途

如果你想用这个 `createLocalSolanaClient` 下面的帮助,请参见可选安装 `createLocalSolanaClient` 节.

```typescript
import { SurfpoolContainer, createLocalSolanaClient } from '@beeman/testcontainers'

// Start the container (offline mode by default)
const container = await new SurfpoolContainer().start()

// Create a client with auto-generated payer
const client = await createLocalSolanaClient({ container })

// Access the Studio URL
const studioUrl = container.urlStudio

// ... run your tests ...

// Stop the container when done
await container.stop()
```

#### 网络选择

连接到特定的索拉纳网络( 离线模式):

```typescript
// Connect to devnet
const container = await new SurfpoolContainer()
  .withSolanaNetwork('devnet')
  .start()

// Or use a custom RPC URL
const container = await new SurfpoolContainer()
  .withRpcUrl('https://my-rpc-provider.com')
  .start()
```

#### 空投配置

启动时SOL的基金前账户:

```typescript
const container = await new SurfpoolContainer()
  .withAirdrop(
    ['5cQvx...', '5cQvy...'],  // List of pubkeys to fund
    100_000_000_000             // Amount in lamports (100 SOL)
  )
  .start()
```

#### 自定义时间

为更快或更慢的块生产调整槽时间 :

```typescript
// Faster slots (100ms instead of default 400ms)
const container = await new SurfpoolContainer()
  .withSlotTime(100)
  .start()
```

#### 块生产模式

控制块的生成方式 :

```typescript
// Transaction-based block production (new block per transaction)
const container = await new SurfpoolContainer()
  .withBlockProductionMode('transaction')
  .start()
```

#### 禁用特性

```typescript
const container = await new SurfpoolContainer()
  .withNoStudio()   // Disable the Studio UI
  .withNoDeploy()   // Disable auto deployments
  .start()
```

#### 完整配置示例

```typescript
// Connect to devnet with custom configuration
const container = await new SurfpoolContainer()
  .withSolanaNetwork('devnet')
  .withAirdrop(['5cQvx...'], 500_000_000_000)
  .withSlotTime(200)
  .withBlockProductionMode('transaction')
  .withLogLevel('debug')
  .start()
```

#### 属性

-   `container.url`: 返回 RPC URL(例如, `http://localhost:32768`) (中文(简体) ).
-   `container.urlWs`: 返回 WebSocket URL(例如, `ws://localhost:32769`) (中文(简体) ).
-   `container.urlStudio`: 返回 Studio URL(例如, `http://localhost:32770`) (中文(简体) ).
-   `container.port`: 返回映射的 RPC 端口.
-   `container.portWs`: 返回已映射的 WebSocket 端口.
-   `container.portStudio`: 返回映射工作室端口.

#### 配置方法

| 方法 | 说明 |
| --- | --- |
| `withSolanaNetwork(network)` | 连接到 `'mainnet'`, (中文(简体) ), `'devnet'`,或 `'testnet'` (残疾离线模式) |
| `withRpcUrl(url)` | 使用自定义的 RPC URL( 离线模式) |
| `withOffline(false)` | 禁用离线模式( 默认启用) |
| `withAirdrop(addresses, amount?)` | 基金前账户(违约:10 000 SOL) |
| `withAirdropKeypairPaths(paths)` | 来自 keypair 文件的基金账户 |
| `withSlotTime(ms)` | 设置空档持续时间( 默认: 400ms) |
| `withBlockProductionMode(mode)` | `'clock'` 或者说 `'transaction'` (默认:时钟) |
| `withNoStudio()` | 禁用工作室用户界面 |
| `withNoDeploy()` | 禁用自动部署 |
| `withLogLevel(level)` | 设置日志级别 : `'trace'`, (中文(简体) ), `'debug'`, (中文(简体) ), `'info'`, (中文(简体) ), `'warn'`, (中文(简体) ), `'error'`, (中文(简体) ), `'none'` |
| `withPort(port)` | 设定 RPC 端口( 默认: 8899) |
| `withWsPort(port)` | 设置 WebSocket 端口( 默认: 8900) |
| `withStudioPort(port)` | 设置工作室端口( 默认: 18488) |

## 公用事业

### `createLocalSolanaClient`

一个创建 Solana RPC 客户端为本地容器配置的便利助手 。 包起来 `createDefaultLocalhostRpcClient` 从 `@solana/kit-plugins` 并且与双方合作 `SolanaTestValidatorContainer` 财务报告和审定财务报表 `SurfpoolContainer`。 。 。 .

要使用此帮助, 请安装 `@solana/kit` 财务报告和审定财务报表 `@solana/kit-plugins`数字 :

```bash
bun add @solana/kit @solana/kit-plugins
```

```typescript
import { SurfpoolContainer, createLocalSolanaClient } from '@beeman/testcontainers'

const container = await new SurfpoolContainer().start()

// Create a client with an auto-generated payer
const client = await createLocalSolanaClient({ container })

// Or provide your own payer
import { generateKeyPairSigner } from '@solana/kit'

const payer = await generateKeyPairSigner()
const client = await createLocalSolanaClient({ container, payer })
```

回来的 `LocalSolanaClient` 提供访问 `rpc`, (中文(简体) ), `rpcSubscriptions`,则 `payer` 签名者.

#### 参数

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `container` | `StartedSolanaTestValidatorContainer | StartedSurfpoolContainer` | 一个开始的容器实例 |
| `payer` | `TransactionSigner` (可选) | 付款人签名人; 自动生成( 如果不提供) |

## 发展

这个项目是用 [阿宝](https://bun.sh/)。 。 。 .

### 图标

-   **构建**数字 : `bun run build`
-   **测试**数字 : `bun test`
-   **林特**数字 : `bun run lint`
-   **类型检查**数字 : `bun run check-types`

## 许可证

麻省理工学院 — 看 [自由主义](https://npmcn.com/package/%40beeman/testcontainers/LICENSE)。 。 。 .

## 常见问题

### @beeman/testcontainers 是什么？

收集资料 测试容器 用真实服务测试您的应用程序\.

### 如何安装 @beeman/testcontainers？

在项目目录运行 npm install @beeman/testcontainers，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@solana/kit（^6）、@solana/kit-plugins（^0\.3）、testcontainers（^11 \|\| ^12）、typescript（^5 \|\| ^6）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @beeman/testcontainers 支持 TypeScript 吗？

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

### @beeman/testcontainers 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @beeman/testcontainers 可以商用吗？

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

### @beeman/testcontainers 的下载量有多少？

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

### @beeman/testcontainers 还在维护吗？

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