# @cypress/fiddle 中文文档

规范地址：https://npmcn.com/package/%40cypress/fiddle/

版本：1\.19\.3
npm 元数据更新时间：2025-10-27T19:17:02.132Z
中文译文更新时间：2026-11-11T07:35:29.446Z
软件包许可：MIT

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

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

弃用说明：Package no longer supported\. Contact Support at https://www\.npmjs\.com/support for more info\.

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

- 包体积（解压后）：29.8 kB，8 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：7 个
- 首次发布：2019-09-05T18:00:28.177Z
- 最新版本发布：2021-12-06T14:03:15.707Z
- 近 30 天下载量：3191（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：39（近 12 个月 0 个）

## 中文简介

从 HTML 和 JS 生成 Cypress 测试

## 安装

```sh
npm install @cypress/fiddle
```

也可以使用：`pnpm add @cypress/fiddle`、`yarn add @cypress/fiddle`、`bun add @cypress/fiddle`

## README

# cypress-小提琴 [![renovate-app badge](https://img.shields.io/badge/renovate-app-blue.svg)](https://renovateapp.com/) [![CircleCI](https://circleci.com/gh/cypress-io/cypress-fiddle/tree/master.svg?style=svg)](https://circleci.com/gh/cypress-io/cypress-fiddle/tree/master)

> 生成来自 HTML 和 JS 的 Cypress 测试

通过创建一个小活的HTML小提琴并运行针对它的E2E测试,对Cypress测试进行即时实验.

![runExample test](https://npmcn.com/package/%40cypress/fiddle/images/runExample.png)

## 安装

Cypress是此模块的同级依赖. 通过运行安装当前版本的 Cypress `npm i -D cypress`。 。 。 .

在安装 Cypress后, 通过 npm 安装此模块 :

```shell
npm i -D @cypress/fiddle
```

然后通过添加以下行来加载自定义命令 `cypress/support/index.js`

```js
// adds "cy.runExample()" command
import '@cypress/fiddle'
```

## 使用

### 创建单一测试

您可以用一个 `html` 包含 HTML 和 a 的属性 `test` 包含 Cypress 命令的属性,并运行测试.

举例来说 `cypress/integration/spec.js` 文件 :

```js
// loads TypeScript definition for Cypress
// and "cy.runExample" custom command
/// <reference types="@cypress/fiddle" />

const helloTest = {
  html: `
    <div>Hello</div>
  `,
  test: `
    cy.get('div').should('have.text', 'Hello')
  `
}

it('tests hello', () => {
  cy.runExample(helloTest)
})
```

产生

![runExample test](https://npmcn.com/package/%40cypress/fiddle/images/runExample.png)

### 参数

测试对象可具有多个属性,参见 [标准/指数.d.ts](https://npmcn.com/package/%40cypress/fiddle/src/index.d.ts) 为所有人.

-   `test` 需要带有 Cypress 命令的 JavaScript

其余的属性是可选的

-   `html` 在测试开始前作为 DOM 节点挂起
-   `name` 在页面上方显示的名称,否则将使用测试标题
-   `description` 名称下的额外测试描述,支持 Markdown 通过 [安全标记](https://github.com/azu/safe-marked)
-   `commonHtml` 是附加到活的 HTML (如果有) 元素上的额外的 HTML 标记。 用于装入外部样式表或样式而无需对每个 HTML 块进行分解

下一个属性不被使用 `cy.runExample` 但用于 `testExamples` 函数.

-   `skip` 创建跳过测试 `it.skip`
-   `only` 创建独家测试 `it.only`

### 包含的脚本

-   [查询已修改](https://code.jquery.com/)
-   [突出内容.js](https://highlightjs.org/)

您可以使用环境变量块在 `cypress.json` 文件

```json
{
  "env": {
    "cypress-fiddle": {
      "scripts": [
        "https://cdn.jsdelivr.net/npm/bootstrap@4.5.3/dist/js/bootstrap.bundle.min.js"
      ]
    }
  }
}
```

### 样式

有时您想要将外部样式表和可能自定义样式 CSS 注入到帧中(我们已经包括了Highlight.js). 通过环境变量通过额外的 CSS 链接 urls 和自定义样式 `cypress.json` 配置文件 .

```json
{
  "env": {
    "cypress-fiddle": {
      "stylesheets": [
        "https://stackpath.bootstrapcdn.com/bootstrap/4.4.1/css/bootstrap.min.css"
      ],
      "style": "body { padding: 1rem; }"
    }
  }
}
```

**提示 :** 设置多行环境变量甚至从插件文件中装入 CSS 文件更为方便.

### 创建多个测试

而不是写 `cy.runExample()` 逐个命令,可以将所有测试定义收集到列表或套件的嵌入对象中,并自动创建测试.

例如,这里列出从数组创建的测试:

```js
import { testExamples } from '@cypress/fiddle'

const tests = [
  {
    name: 'first test',
    description: 'cy.wrap() example',
    test: `
      cy.wrap('hello').should('have.length', 5)
    `
  },
  {
    name: 'second test',
    description: 'cy.wrap() + .then() example',
    test: `
        cy.wrap()
          .then(() => {
            cy.log('In .then')
          })
      `
  }
]
testExamples(tests)
```

![List of tests](https://npmcn.com/package/%40cypress/fiddle/images/list.png)

在进行测试的同时,可以跳过测试或者使其具有独家性. 例如,跳过第一个测试时添加一个 `skip: true` 属性.

```js
{
  name: 'first test',
  description: 'cy.wrap example',
  skip: true
  ...
}
```

或通过使用 `only: true` 属性.

```js
{
  name: 'first test',
  description: 'cy.wrap example',
  only: true
  ...
}
```

你可以通过有嵌入物来创建套房. 每个物体要么成为套房,要么成为测试.

```js
import { testExamples } from '@cypress/fiddle'
const suite = {
  'parent suite': {
    'inner suite': [
      {
        name: 'a test',
        html: `
          <div id="name">Joe</div>
        `,
        test: `
          cy.contains('#name', 'Joe')
        `
      }
    ],
    'list test': {
      html: `
        <ul>
          <li>Alice</li>
          <li>Bob</li>
          <li>Cory</li>
        </ul>
      `,
      test: `
        cy.get('li').should('have.length', 3)
          .first().should('contain', 'Alice')
      `
    }
  }
}

testExamples(suite)
```

![Tree of tests](https://npmcn.com/package/%40cypress/fiddle/images/tree.png)

查找更多实例 [细胞压/整合](https://npmcn.com/package/%40cypress/fiddle/cypress/integration) 文件夹.

### 标记

这个软件包包括一个JS/CoffeeScript/Markdown预处理器,可以在其中找到并运行测试 `.md` 文档。 只要用这样的 HTML 注释包围测试:

````
<!-- fiddle Test name here -->
Add additional text if you want. HTML code block is optional.

```html
<div>Example</div>
```

Test code block that should be run as a test
```js
cy.contains('Bye').should('be.visible')
```
<!-- fiddle-end -->
````

参见示例 [bahmutov/vuepress-cypress-测试-实例](https://github.com/bahmutov/vuepress-cypress-test-example) 财务报告和审定财务报表 [现场现场](https://vuepress-cypress-test-example.netlify.com/)。阅读博客文章 [从 Markdown 文件运行端到端测试](https://glebbahmutov.com/blog/cypress-fiddle/) 财务报告和审定财务报表 [自测试 JAM 页面](https://www.cypress.io/blog/2019/11/13/self-testing-jam-pages/)。 。 。 .

您可以有常见的 HTML 块并分解测试到多个 JavaScript 代码块. 这对一步一步地解释试验很有用

````
This test has multiple parts. First, it confirms the string value
```js
cy.wrap('first').should('equal', 'first')
```
Then it checks if 42 is 42
```js
cy.wrap(42).should('equal', 42)
```
````

实际测试是

```js
cy.wrap('first').should('equal', 'first')
cy.wrap(42).should('equal', 42)
```

### 仅跳过

你可以跳过小提琴,或者只运行一个类似于 `it.skip` 财务报告和审定财务报表 `it.only`

```
<!-- fiddle.skip this is a skipped test -->
<!-- fiddle.only this is an exclusive test -->
```

**说明:** 还有 `fiddle.export` 修饰相. 这些小提琴在从Markdown进行正常测试时被跳过,但在输出JavaScript specs中导出并启用.

### 页面标题

如果 Markdown 文件有类似页面标题行 `# <some text>`,用于创建顶级测试套件

```js
describe('<some text>', () => {
  // tests
})
```

### 嵌入式套房

你可以把小提琴放进套房 `/` 作为分隔符

```
<!-- fiddle Top / nested / test -->
```

将创建

```js
describe('Top', () => {
  describe('nested', () => {
    it('test', () => {})
  })
})
```

### 直播 HTML

在小提琴中可以包括"活"html块——这样的话它们就会成为测试碎片.

````
<!-- fiddle includes live html -->
<div id="live-block">Live Block</div>
```js
cy.contains('#live-block', 'Live Block').should('be.visible')
```
<!-- fiddle-end -->
````

在包含HTML源片段和活的HTML块时,活的HTML块获胜并会被作为测试片段使用.

````
<!-- fiddle includes both live and html block -->
```html
<div id="my-block">Block</div>
```

<div id="live-block">Live Block</div>

```js
// when including both live HTML block and
// html code block, the live HTML block wins
cy.contains('#live-block', 'Live Block').should('be.visible')
cy.contains('#my-block', 'Block').should('not.exist')
```
<!-- fiddle-end -->
````

### 常见 Live HTML

如果您要在 HTML 块前装入通用的 HTML, 但不想在 HTML 片断中显示, 请将它放入这样的评论中

```
<!-- fiddle-markup
<link rel="stylesheet" href="some CSS URL">
<style>
body {
  padding: 2rem;
}
</style>
-->
```

您可以使用这种方法加载样式和外部的CDN脚本.

### 隐藏小提琴在Markdown

你可以"躲"在Markdown内部的小提琴 这样一页 _可以测试自己_。见 [cypress/集成/隐藏-中小.md](https://npmcn.com/package/%40cypress/fiddle/cypress/integration/hidden-fiddle.md) 实例.

**标记**

![Hidden fiddle Markdown](https://npmcn.com/package/%40cypress/fiddle/images/hidden-fiddle.png)

**渲染页面**

![Hidden fiddle Markdown preview](https://npmcn.com/package/%40cypress/fiddle/images/hidden-fiddle-preview.png)

注意只显示摘要的方式

**测试运行器**

![Hidden fiddle test](https://npmcn.com/package/%40cypress/fiddle/images/hidden-fiddle-test.png)

**说明:** 默认情况下,摘要元素在 HTML 中显示。 你可以完全使用小提琴

```html
<details style="display:none">
 ...
</details>
```

#### 安装

在您的插件文件使用中

```js
const mdPreprocessor = require('@cypress/fiddle/src/markdown-preprocessor')
module.exports = (on, config) => {
  on('file:preprocessor', mdPreprocessor)
}
```

进 `cypress.json` 文件允许 Markdown 文件

```json
{
  "testFiles": "*.md"
}
```

警告: [第5401号问题](https://github.com/cypress-io/cypress/issues/5401)

## 从Markdown小提琴导出JS规格

```shell
# saves path/to/md.js file
npx export-fiddle <path/to/md>
# adds optional "beforeEach" hook with cy.visit(url)
npx export-fiddle <path/to/md> --before-each <url>
# adds optional "before" hook with cy.visit(url)
npx export-fiddle <path/to/md> --before <url>
```

## 调试

查看调试日志, 使用 `DEBUG=@cypress/fiddle` 当运行 Cypress 时.

## 出版

在 CircleCI 上使用自动语义发布 [环形圆形](https://github.com/cypress-io/circleci-orb),参见 [圆. yml](https://npmcn.com/package/%40cypress/fiddle/circle.yml) 文档.

## 常见问题

### @cypress/fiddle 是什么？

从 HTML 和 JS 生成 Cypress 测试注意：该包已被作者标记为弃用——Package no longer supported\. Contact Support at https://www\.npmjs\.com/support for more info\.

### 如何安装 @cypress/fiddle？

在项目目录运行 npm install @cypress/fiddle，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 export-fiddle，可以用 npx export-fiddle 直接运行。

### @cypress/fiddle 支持 TypeScript 吗？

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

### @cypress/fiddle 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @cypress/fiddle 可以商用吗？

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

### @cypress/fiddle 的下载量有多少？

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

### @cypress/fiddle 还在维护吗？

最新版本 1\.19\.3 发布于 2021/12/06（4 年前）；至今共发布 39 个版本，其中过去 12 个月发布了 0 个；首次发布于 2019/09/06。作者已将其标记为弃用，新项目建议寻找替代方案。