CKEditor 生态系统文档
Search
Contribute to this guide
首页/CKEditor 5/框架

guide测试环境

在阅读本文之前，我们建议您熟悉 CKEditor 5 的开发环境。

# 简介

CKEditor 5 测试环境使用 Karma、webpack、babel-loader 和 Istanbul 的流行设置。我们创建了一些 npm 脚本，将所有这些部分和 CKEditor 的特殊需求整合在一起。

每个 CKEditor 5 包都有自己的测试套件（例如，请参见 引擎测试）。但是，测试运行程序位于 ckeditor5 存储库的根目录中，它是中央开发环境。测试运行程序的实际代码在 @ckeditor/ckeditor5-dev-tests 包中实现，可以在 ckeditor5 之外重用。

自动化测试和手动测试都支持 TypeScript。只需使用 .ts 扩展名即可。

# 运行自动化测试

要运行自动化测试，请使用 yarn run test [<args>...] 命令。

它接受以下参数，这些参数必须在 -- 选项之后传递

  • --watch（别名 -w） – 是否监视文件并在任何文件更改时执行测试。
  • --source-map（别名 -s） – 是否为代码生成有用的源映射。
  • --coverage（别名 -c） – 是否生成代码覆盖率。
  • --verbose（别名 -v） – 允许启用 webpack 日志。
  • --files – 指定要运行的测试文件。请参阅 使用 --files 选项的规则 部分。
  • --browsers – 将用于运行测试的浏览器。默认为 Chrome。
  • --port – 指定服务器要使用的端口。默认为 9876。
  • --identity-file="/path/to/file.js"（别名 -i） – 包含封闭源代码功能许可证密钥的文件的路径。

# 示例

运行 ckeditor5-core 包的代码覆盖率检查的所有测试

yarn run test -c --files=core

运行并监视代码覆盖率检查 引擎的 view 命名空间测试 以及 ckeditor5-typing 中的所有测试

yarn run test -cw --files=engine/view/,typing

运行并监视 ckeditor5-basic-styles 包中的 bold*.js 测试

yarn run test -w --files=basic-styles/bold*

# 自定义 Chai 断言

测试环境允许使用一些自定义 Chai 断言。无需导入它们，因为它们在所有测试中默认导入。

# equalMarkup

测试两个包含标记语言的给定字符串是否相等。与 Chai 断言库中的 expect().to.equal() 不同，此断言在显示差异之前会格式化标记。它可用于测试 HTML 字符串和包含序列化模型的字符串。

此断言将通过

expect( `<b>foo</b>` ).to.equalMarkup( `<b>foo</b>` )

此断言将抛出错误

expect(
    '<paragraph>foo bXXX[]r baz</paragraph>'
).to.equalMarkup(
    '<paragraph>foo bYYY[]r baz</paragraph>'
);

# attribute

断言目标具有给定键名的属性。请参阅 hasAttribute。

expect( selection ).to.have.attribute( 'linkHref' );

当提供可选的 value 时，.attribute 还断言属性的值等于给定的 value。请参阅 getAttribute。

expect( selection ).to.have.attribute( 'linkHref', 'example.com' );

否定也适用。

expect( selection ).to.not.have.attribute( 'linkHref' );

# 运行手动测试

要启动手动测试服务器，请使用 yarn run manual 任务。调用此命令后，系统可能会询问您是否要重新创建 DLL 构建。您不必每次运行手动测试时都重新创建 DLL 构建。仅当您要检查这些测试中的更改时才执行此操作，这些测试需要 DLL 构建。

您可以在 专用指南 中详细了解 DLL 构建。

yarn run manual 任务接受以下选项

  • --files – 指定要运行的测试文件。请参阅 使用 --files 选项的规则 部分。
  • --language="pl" – 构建到所有测试编辑器中的主要语言，传递到 CKEditor 5 翻译插件。查看 UI 语言指南 以了解更多信息。如果未指定，则 'en' 将传递到测试运行程序。
  • --additional-languages="ar,pl,..." – 指定传递到 CKEditor 5 翻译插件 的额外语言。查看 UI 语言指南 以了解更多信息。
  • --debug（别名 -d） – 允许指定自定义调试标志。例如，--debug engine 选项会取消注释代码中的 // @if CK_DEBUG_ENGINE // 行。请注意，默认情况下，即使您未指定 --debug，它也会设置为 true。这会启用基本调试日志集（// @if CK_DEBUG //），这些日志应该始终在测试环境中启用。您可以通过设置 --debug false 选项来完全关闭调试模式。
  • --port – 指定服务器要使用的端口。默认为 8125。
  • --identity-file="/path/to/file.js"（别名 -i） – 包含封闭源代码功能许可证密钥的文件的路径。
  • --dll – 一个可选标志，允许在不征求用户确认的情况下自动创建 DLL 构建。如果为 true（表示提供了 --dll 标志），则如果测试文件需要 DLL 构建，则会自动创建 DLL 构建。您可以通过提供 --no-dll 标志来否定逻辑，以永不创建 DLL 构建，也不询问用户。默认为 null，因此会询问用户以进行确认。
  • --disable-watch – 当没有指定 --files 时，默认情况下会启用它。这是因为在所有文件上运行观察程序时会占用大量内存。禁用监视模式会导致文件在更改时不再自动重建。

它启动了可在 https://127.0.0.1:8125 上访问的服务器。

# 创建手动测试

手动测试包含 3 个文件

  • 一个带有测试描述的 <name>.md 文件。
  • 一个带有测试的 JavaScript 或 TypeScript 部分的 <name>.js 或 <name>.ts 文件（例如，初始化编辑器的代码）。
  • 一个带有测试的 HTML 部分的 <name>.html 文件。它不需要是完整的 HTML 页面（带有 DOCTYPE 等）。它可以只包含要定义的 HTML 元素。

所有 3 个文件组合在一起，创建一个单一的手动测试。

一个 Markdown 文件示例

## Create a new link

1. Select a fragment of the regular text.
2. Click the toolbar "Link" button.
3. Check if the balloon panel attached to the selection appeared.
4. Fill in the "Link URL" input in the panel.
5. Click the "Save" button.
6. Check if the selected text is converted into a link.

一个 HTML 文件示例

<head>
    <style>
        /*
          Some additional styles which this test needs.
          And yes – the test builder will merge this tag with the head defined in the template.
        */
    </style>
</head>

<div id="editor">...</div>

一个 JavaScript 文件示例

/* globals console, window, document */

import { ClassicEditor, Essentials, Paragraph } from 'ckeditor5';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Essentials, Paragraph ]
    } )
    .then( editor => {
        window.editor = editor;
    } )
    .catch( err => {
        console.error( err.stack );
    } );

不要忘记将手动测试的所有依赖项添加为 devDependencies（在 package.json 中）。

我们建议使用官方的 CKEditor 5 检查器 进行开发和调试。它将为您提供有关编辑器状态的大量有用信息，例如内部数据结构、选择、命令等等。

manual/ 测试目录应始终位于 tests/ 目录的根目录中。

  • packages/ckeditor5-engine/tests/manual/view/focus.js – 正确路径。
  • packages/ckeditor5-engine/tests/view/manual/focus.js – 错误路径。

# 验证所有手动测试

要验证所有手动测试都可以在没有错误的情况下打开（爬虫不会执行手动测试步骤，它只会访问页面），您无需手动逐页进行。相反，有一个网络爬虫会自动遍历文档并访问已找到的所有页面。爬虫会打开一个无头 Chromium 浏览器，并将已找到的任何错误记录到控制台。

要检查手动测试，请启动服务器（yarn manual --files=XYZ），然后运行爬虫

yarn run manual:verify

在 验证文档 指南中详细了解爬虫。

# 使用 --files 选项的规则

--files（别名 -f）选项由手动测试和自动化测试使用，它接受以下类型的模式

模式 结果
ckeditor5 运行根 ckeditor5 包的所有测试。
核心 运行 ckeditor5-core 包的所有测试。
build-* 运行 build-* 包的所有测试。（ckeditor5-build-classic，ckeditor5-build-balloon 等）
!core 运行所有测试，除了 ckeditor5-core 包的测试。
!(core|engine) 运行所有测试，除了 ckeditor5-core 和 ckeditor5-engine 包的测试。可以排除任意数量的包。
engine/view/ 运行位于 ./packages/ckeditor5-engine/tests/view/ 目录中的 ckeditor5-engine 包的所有测试。
core/editor/utils/ 运行位于 ./packages/ckeditor5-core/tests/editor/utils/ 目录中的 ckeditor5-core 包的所有测试。
basic-styles/bold 运行 ckeditor5-basic-styles 包中文件名名为 bold.js 的所有测试。
basic-styles/bold* 运行 ckeditor5-basic-styles 包中文件名匹配 bold*.js 模式的所有测试。
  • ./packages/ckeditor5-basic-styles/tests/bold.js
  • ./packages/ckeditor5-basic-styles/tests/bold/boldediting.js
  • ./packages/ckeditor5-basic-styles/tests/bold/boldui.js
ckeditor5,list/list/,style/*grid* 所有参数的总和，以逗号 , 分隔。此模式可以使用任何类型的参数组合。请注意，由于它是总和，使用多个 !foo 排除参数可能无法按预期工作。

可以使用逗号 , 分隔的多个参数来获得编译输出的总和。

所有模式都支持 * 通配符。

# 测试套件和 CI

为了确保最高质量，我们维护一个完整的测试套件，每个包都有稳定的 100% 代码覆盖率。截至 2019 年 9 月，这意味着超过 11000 个测试，并且这个数字还在不断增长。由于每个包都是独立测试的，我们为库实现了低级测试，为最终用户功能实现了高级测试。

如此广泛的测试套件需要一个适当的持续集成服务。我们使用 Travis CI 作为构建平台。此服务确保无缝且快速的开发人员体验，并允许我们专注于工作。

除了自动化测试，我们还维护了一套较小的手动测试。它们帮助我们验证是否发生了一些自动化测试可能遗漏的意外情况。

在提出拉取请求时，请确保添加验证它的测试。每个代码更改都应该伴随着一个测试，证明它是必要的。这种严格的测试方法确保我们不仅拥有 100% 的代码覆盖率（这很容易实现并且只提供了虚幻的安全感），而且还拥有很高的覆盖率，用于我们最初没有注意到（并且将来可能再次发生）的用例。