密码接字板

A 类 密码JS 将一个Gherkin情景转换成一个人可读的故事板的插件,直接从真实的截图中取出测试抓取. Markdown是默认;在想要自成一体的图片时明确选择SVG.

单格金句=一卡通=一像素基线,在其步骤中断言: tolerance: 0:在图像漂移的确切句子上,视觉回归失败. 当情景结束时,Markdown会同时显示可读标题,注释和可复制命令的截图. 它链接了原始截图而不是嵌入其字节,因此审查者可以直接以GitLab打开文件. SVG嵌入了截图并保留了可以选择的文字围绕(Chrimium/Safari).

安装

npm install --save-dev codeceptjs playwright @digital-commons-official/codeceptjs-storyboard @digital-commons-official/codeceptjs-visual-helper
npx playwright install chromium

需要节点.js >= 22.19.0密码 ^4.2.0 财务报告和审定财务报表 @digital-commons-official/codeceptjs-visual-helper >= 1.3.0。插件通过 I.takeScreenshot, (中文(简体) ), I.captureScreenshot 财务报告和审定财务报表 I.assertVisualMatch。 。 。 .

需要Visual Helper:在CodeceptJS中启用,如下文所示. 保持它作为对等依赖,让插件使用您的工程的帮助和CodeceptJS安装.

测试过的版本

浏览器套件将实际打包的包装入六个新鲜项目:

每个项目都进口自己的四个包裹,通行证 npm audit,记录 1 英语旅行和三个法语规则案例,然后用严格的像素重播 比较。 所有14个基线散列必须保持不变并相互匹配 六个组合。 每个项目也会运行默认的 Markdown 格式,反对 检查所有四个马克登画廊链接.

18号节点被拒绝 --engine-strict; 代码接受JS 4.0 以 --strict-peer-deps旧法典 4.0 消费者也未能进行安全审计. 所声明的范围允许以后的相容版本;表格显示准确的 使用 CI 的版本。 当 比较机器之间的图片.

这些安装测试的使用 npm pack 和真正的 npm 命令。 他们没有 认证出版物至登记处;只认证成功发布工作 提供这种单独的证据。 发布使用 GitLab OIDC 认证而不使用 a 存储 npm 令牌并只在受保护的默认分支上运行。 npm 来源 被明确禁用,因为 npm 拒绝自办的证明 因此这些释放不包括npm出处证明.

公共 API 和兼容性

包根会导出 CodeceptJS 插件厂和这些功能. 其签名定义如下: 标准/指数.d.ts。 。 。 .

支持的插件选项是 format, (中文(简体) ), theme, (中文(简体) ), markdown 财务报告和审定财务报表 replayCommand; CodeceptJS 拥有 require 财务报告和审定财务报表 enabled。从 1. 0. 0 起,兼容的发布会维护此公开性 API和所记录的基准记录行为. 移除公众 函数,更改其所需的参数或提高支持的最小值 需要主要释放。 内部模块 src/ 正在执行 细节; 使用包根.

剖析器遵循了Cucumber的Gherkin方言. 特征和规则背景, 方案大纲和实例、继承标记、重复标题、数据表 并支持医生字符串。 真正的浏览器行程包括英语、法语 和德文;解析测试覆盖了其他方言,包括相接的关键词. 表格和医生字符串是步骤参数,而不是额外的卡. 过滤运行 没有匹配方案失败。 未来依赖性版本仍然需要 相同的相容性检查;上面的矩阵识别已验证的版本.

配置 {}

在视觉帮助器旁边注册插件 codecept.conf.js,将Gherkin指向您的步骤文件:

exports.config = {
  output: './_output',
  noGlobals: true,
  helpers: {
    Playwright: {
      browser: 'chromium',
      url: 'http://localhost:8080',
      show: false,
      windowSize: '1280x720'
    },
    VisualHelper: {
      require: require.resolve('@digital-commons-official/codeceptjs-visual-helper'),
      baselineDir: './screenshots/base/',
      diffDir: './screenshots/diff/',
      actualDir: './_output/',
      tolerance: 0,
      captureBaseline: false
    }
  },
  gherkin: {
    features: './features/**/*.feature',
    steps: ['./steps/first-run.js']
  },
  plugins: {
    storyboard: {
      require: '@digital-commons-official/codeceptjs-storyboard',
      enabled: true
    }
  }
}

选择一个格式

奥米 format 或设置 format: 'markdown' 为了马克道 设定 format: 'svg' 用于 SVG :

storyboard: {
  require: '@digital-commons-official/codeceptjs-storyboard',
  enabled: true,
  format: 'svg'
}

每个运行生成一个格式 。 阵列, both, (中文(简体) ), md, (中文(简体) ), null 其他价值观则遭到拒绝。 Markdown 是一个破解默认更改: 添加 format: 'svg' 以保留较早的 SVG 文件和 HTML 画廊。 现有独立 render('board.svg', options) 电话还是SVG.

路径来源于特性文件位置. 框架在 _output/storyboard-frames/ 和基准 screenshots/base/<feature-dir>/<scenario-tag>/。 。 。 .

一个没有被捕获的帧的场景不会产生故事板,因此平庸的格金测试没有受到任何影响.

当运行结束时,打开所选的画廊来浏览其故事板. 它通过功能目录来组合情景,将失败的组合和情景放在首位,并用它的回放命令来显示失败的句子. 链接打开所选格式.

过滤过的运行只列出它运行的情景 。 在基线更新模式下,被审查的画廊从该更新中列出了经过的情景;失败的情景从未取代被审查的故事板. 在更新模式中运行完整的套件以重建完整的被审查的画廊. 先前运行或其它格式的文件不会被删除或添加到当前相册中.

在分支上读取 Markdown 或合并请求

将生成的文件提交到 storyboards/ 及其经审查的截图 screenshots/base/。 。 。 . 在正在审查的分支上打开 Markdown 文件 。 相对图像链接使用相同的修改; 后 合并,打开目标分支上的文件使用合并的图像. 没有分支名称, GitLab 主机名或 符号存储在文档中。 一个被删除的源分支的 URL 不自动重定向 .

譬如说, storyboards/login/sign-in.md 可链接到 ../../screenshots/base/login/sign-in/form.png。这些路径也在本地的Markdown取景器中工作,仓库布局完好无损。 这适用于寄存器文件;将其内容粘贴到MR描述中使用了不同的链接上下文.

运行时间 Markdown 引用了实际捕获,如果失败,则引用了预期/diff/ 实际图像. 保留 _output/ 财务报告和审定财务报表 screenshots/ 。在下载报告时,在原始相对布局中。 一个Markdown文件本身并不包括它的图像. SVG是自成一体的选择. 仓库渲染并不意味着GitLab的CI文物取景器预览了Markdown.

Markdown保存章节,句子顺序,注释,多语种关键词和失败信息. 页面标题为情景,下行有特有内容,以其关键词命名 特性文件。 然后,报告提供了记录的结果和框架/步骤,然后是与各章的链接, 结果和重放信息。 一个没有明确结果的独立版本说 "结果没有记录";它不会从没有视觉失败推断成功.

每章从平平的Markdown标题开始. 屏幕截图默认坐落在两个等宽的柱子上. 每张牌都留着 其标题、图像、注释和可复制命令一起。 每个对子都有自己的桌子 所以GitLab不放 在一个滚动区域内的整章。 单行命令在其注释下显示为内置代码, 来包装,所以两列都保持宽度; 多行的命令显示为打开的代码块. 倒放和源细节在结尾折叠. 一个失败的比较保留了预期 / Diff / 实际和不可用图像 标签可见,无论细节设置如何.

标记下布局

直接在插件上配置演示文稿; 不需要 CSS 文件 :

storyboard: {
  require: '@digital-commons-official/codeceptjs-storyboard',
  enabled: true,
  markdown: {
    columns: 2,
    tableOfContents: true,
    technicalDetails: 'collapsed'
  }
}

示例显示默认值. 设定 columns: 1 用于全宽卡片,特别是读取时 窄相屏. GitLab 表格不会像响应的 HTML 网格那样自动堆放. 设定 technicalDetails: 'expanded' 打开重播和源细节,或 tableOfContents: false 以省略导航。 两个选项都无法删除证据或注释 .

不支持的选项和无效的布局值会在插件注册前引起一个明显的错误 听者或独立出品者会写出文物.

GitLab通过读者偏好来控制页面背景,字体和本土提醒颜色. 基本信息 即使在图像无法装入时仍为文本 。 渲染器从不重排截图, 装入外部 资产,或只应用 SVG theme 选项。 明确 format: 'svg' 保持其现有 主题行为和忽略 Markdown 演示文稿设置.

独立呼叫者可以使用 render('report.md', { markdown: { columns: 1 }, outcome: 'passed' })。 。 。 . 只提供 outcome ; 失败证据总是优先于所传递的价值.

重放命令

画廊和故事板默认为 npx codeceptjs run --steps --grep "{tag}"。 。 。 . {tag} 成为剧情的最后标记。 这个命令独立运行 CodeceptJS项目带有本地安装及其默认配置文件.

工具箱项目可以在插件上设置任务命令 :

storyboard: {
  require: '@digital-commons-official/codeceptjs-storyboard',
  enabled: true,
  replayCommand: 'task test -- --grep "{tag}"'
}

对于另一个配置文件,请包含其 --config 参数. 使用独有的情景标记,以便命令选择预定的行程.

颜色和字体

在 SVG 模式下设定 theme 用于对象、 CSS 文件路径或 HTTP( S) URL 的故事板插件:

storyboard: {
  require: '@digital-commons-official/codeceptjs-storyboard',
  enabled: true,
  format: 'svg',
  theme: './storyboard.css'
  // Or: theme: 'https://example.org/storyboard.css'
  // Or: theme: { bg: '#f6f8fb', text: '#192b3d', sans: 'Georgia, serif' }
}

包含 codecept.conf.js。插件每次运行一次,在第一种情景的步骤之前加载主题,并将其值嵌入每个 SVG 中。 远程请求5秒后超时 。 缺少, 无法获取或无效的主题会发出警告并使用默认的黑暗主题 .

:root {
  --sb-bg: #f6f8fb;
  --sb-card: #ffffff;
  --sb-slot: #edf2f8;
  --sb-text: #192b3d;
  --sb-dim: #42576b;
  --sb-accent: #175fa4;
  --sb-code-bg: #e7eef7;
  --sb-given: #356b16;
  --sb-when: #175fa4;
  --sb-then: #7b3990;
  --sb-font-sans: Georgia, serif;
}

支持的对象密钥为 bg, (中文(简体) ), card, (中文(简体) ), slot, (中文(简体) ), text, (中文(简体) ), dim, (中文(简体) ), accent, (中文(简体) ), badge, (中文(简体) ), codeBg, (中文(简体) ), given, (中文(简体) ), when, (中文(简体) ), then, (中文(简体) ), fail, (中文(简体) ), sans 财务报告和审定财务报表 mono。 。 。 . CSS 用途 --sb-<key>时,除 codeBg 变成 --sb-code-bg,并使用字体 --sb-font-sans 财务报告和审定财务报表 --sb-font-mono。 。 。 . 输入值保持默认值 。 颜色接受六分法,命名颜色, rgb() 财务报告和审定财务报表 hsl() 值; 字体接受已安装的字体家族名和倒置列表.

只有这些属性被读取 。 导入,外部字体和任意的CSS规则没有被嵌入. SVG在下线工作;在匹配打字重要的机器上安装相同的字体. 主题改变被捕获框周围的标签和牌;截图像素不变.

使用量 +++

这个 .feature 是人类唯一授权的来源

在下面的句子上附上结构化的评论. 特性文件携带故事,步骤文件只驱动并抓取:

• # Chapter: Title 在那张卡片前打开一节(在SVG中是全宽带).
• # Note: text 这是卡片的解释:看什么,为什么它很重要。 重复行以叠出段落.
• # Copy: command 是用卡片显示的准确的可复制命令.

情景下的LAST标记将基准目录和重放命令命名在板上.

@e2e @first-run
Feature: A developer opens their new project
  Scenario: The project home shows the framework
    # Chapter: The empty project
    # Note: The project as GitLab shows it, before anything is installed.
    # Copy: http://gitlab/<user>/<project>
    Given a fresh project with only a README on its main branch

步骤文件驱动和抓取

/* global inject Given */
const { I } = inject()
const storyboard = require('@digital-commons-official/codeceptjs-storyboard')

storyboard.storyboardStep(Given, 'a fresh project with only a README on its main branch', async () => {
  await I.amOnPage('/my/project')
  await storyboard.addStoryboardFrame(I, await storyboard.capturePageFrame(I, 'project-home'))
})

• storyboardStep(register, sentence, fn) 登记台阶并逃离了黄瓜表达元特征,所以 CI/CD 或者说 (y/N) 在句子中永远不要打破比赛。 每句自动打开卡片.
• capturePageFrame(I, name) 抓取整个取景口; captureElementFrame(I, name, selector) 将框架剪成一个元素,所以一个简短的判决产生一个短卡.
• addStoryboardFrame(I, png) 拒绝空白相框,将相框附在开卡上,并立即按自己的基线声明. 在漂移时错误命名了帧,像素diff,失败的故事板和重生基线的命令.
• annotate({ note, copy }) 覆盖特性注释中仅在运行时已知的值.

PNG 或 WebP 帧

框架保留了VisualHelper所写的格式:PNG上至其第2版,默认从第3版起为无损失的WebP(PNG)imageFormat) (中文(简体) ). 基线,Markdown链接和SVG图像跟随帧. 一个经过审查的基线仍然是巴布亚新几内亚的WebP框架被拒绝,因为帮助者会把它记录为一个新的基线,并没有任何比较. 用相同的像素转换已审查基线一次:

npx -y -p @digital-commons-official/codeceptjs-storyboard codeceptjs-storyboard-webp tests/e2e/screenshots/base

Gherkin 语言和实例

设定 # language: fr 地物文件一行(或另一种Cucumber方言). 没有这个标题,Gherkin使用英语. 故事板保留了源关键字,口音和情景标题,包括直接加入句子的关键字. 在您的 CodeceptJS 步骤定义中注册翻译的句子 .

背景步骤和大纲示例以执行顺序出现. 每个实例行都有自己的故事板和基线目录,有一个 -example-<line> 后缀。 重复的句子保留着自己的说明.

# Chapter, (中文(简体) ), # Note 财务报告和审定财务报表 # Copy 仍然是每种语言的注解键; 大纲值也在其中被替换。 doc 字符串和数据表格中的文本不会成为额外的卡片或注释.

无效的语法或未知的方言产生一个命名特征文件的错误. 启用的插件完成 CodeceptJS 的 Gherkin 加载器 Rule 假设情景, 包括本地关键字,例如 Règle。特性背景运行于 每一案件; 规则背景只适用于该规则中的案件。 概要示例 保留单独的测试,并可以选择规则标记 --grep重复 不同规则中的情景标题保留自己的源代码说明. 空选择显然失败, 而不是以零测试成功 .

这个 多语言故事板 运行英语,法语和德语的例子,并显示一个法语句子上真实的视觉回归.

这个 规则故事板 执行 两个法文例和第二个规则,检查背景和 标记过滤器,并证明故意视觉回归的准确句子.

你得到的东西

• 每次运行时, 选中的故事板都写在 _output/<feature-dir>/<scenario-tag>.md 或者说 .svg。 。 。 .
• 在SVG中,卡片每行坐2个,每个708px. 一个框架仍然有1000个px宽或不止一次被安装在1100个px高限上,例如一个网页1440个px宽,取出一个完整的1440个px行并显示其真实大小. 狭长的一行半个 缩成一行 单打一通卡片就在里面.
• 在一次失败的运行中,故事板会显示预期的图像,被更改的像素和带有路径的实际图像,然后列出运行从未到达的句子. SVG将比较呈现为红色波段;Markdown使用标签表.
• 在基线更新模式中,插件首先声明并重写一个基线,只有当其断言失败时,然后重建下面被审查的故事板 storyboards/ 从经审评的基线:

TASK_E2E_UPDATE_BASELINES=1 npx codeceptjs run

只有准确的值 1 能够录制。 一个空值, 0 或者说 false 保留 严格比较。 必须检查以记录方式记录的每个基线 由人类, 这就是为什么模式 扔,当 CI 已经设定.

API —— ——

类型定义 src/index.d.ts。独立渲染使用独立于插件配置的输出扩展并拒绝其他扩展.

联合国

task build                              # install dependencies + build the e2e runner image
task test                               # unit tests, then the e2e storyboard suite
task project:test:storyboard            # unit tests only (vitest)
task project:test:storyboard:e2e        # e2e storyboard suite only, inside the pinned Playwright runner
task project:test:storyboard:markdown   # render the four selected review journeys as Markdown
task project:test:storyboard:svg        # render the remaining review journeys as SVG
task project:test:storyboard:e2e -- --grep "@storyboard-happy-path"
TASK_E2E_UPDATE_BASELINES=1 task project:test:storyboard:svg
TASK_E2E_UPDATE_BASELINES=1 task project:test:storyboard:markdown
task code                               # linters (MegaLinter)

E2e套接字是插件本身的狗粮: 每一种情景都是由测试中的插件所提供的故事板, 执行于 tests/e2e/storyboards/。 。 。 .

打开 标记下画廊 合并请求 分支用于审查安装,Gherkin规则,兼容性和有相对截图链接的Markdown消费者. 重新生成 这些审查的Markdown文件 TASK_E2E_UPDATE_BASELINES=1 task project:test:storyboard:markdown。 。 。 . 主套件明确选择SVG保留其现有的SVG回归覆盖. 使用以上两个记录命令来保存已审查的格式选择,然后检查生成 董事会。 SVG的录制任务 完全排除了这四个马克下行.

这个 安装故事板 将当前来源打包,将沥青球安装到新项目中,并以明确的SVG选择方式运行README配置. Markdown消费者行分别练习省略格式默认. 它检查了CodeceptJS 4.2.0, Playwright 1.63.0和Chrimium的视觉辅助者 1.3.5. 它打开生成的 index.html 和 SVG,以严格的基线重复运行,然后证明一个已更改的页面在准确的句子上失败.

这个 消费清单 固定这些工具,并覆盖脆弱的中转 依赖性。 它的锁文件使得测试可以重复. 分开 版本 矩阵 验证上列六相. 完整的安装和运行日志保存在内 tests/e2e/_output/consumer-install.log 财务报告和审定财务报表 tests/e2e/_output/matrix/。 。 。 .

清洁消费者测试还复制了生成的相册的回放命令 然后检查每个严格的基线散列是否完好无损.

许可证 QQ

欧盟PL-1.2