README

Sitegeist.Monocle风格指南的BackstopJS连接器

此包实现了命令./flow backstop:Configuration，用于创建整个Monocle风格指南的BackstopJS配置文件，以测试所有视图中的所有propSets原型。生成的配置和场景可以通过包设置或通过@styleguide.options.backstop进行调整。

作者和赞助商

Martin Ficzel - ficzel@sitegeist.de

本包的开发和公开发布得到了客户https://www.cornelsen.de和雇主https://www.sitegeist.de的大力赞助。

安装

通过packagist运行composer require sitegeist/monocle-backstopjs获取Sitegeist.Monocle.BackstopJS。

我们使用语义版本控制，每次重大更改都会增加主版本号。

基本教程

安装BackstopJS: npm install -g backstopjs或安装BackstopJS作为项目的开发依赖项
Sitegeist.Monocle.BackstopJS: composer require sitegeist/monocle-backstopjs
创建BackstopJS配置: ./flow backstop:configuration --package-key Vendor.Site --base-uri http://127.0.0.1:8081 > custom-backstop.json
启动Flow Web服务器: FLOW_CONTEXT=Development/VisualRegressionTesting ./flow server:run
创建参考文件: backstop reference --config=custom-backstop.json
运行测试: backstop test --config=custom-backstop.json

CLI命令

该包提供了一个CLI命令，可以针对给定的站点包和baseUri动态创建BackstopJS配置。

USAGE:
  ./flow backstop:configuration [<options>]

OPTIONS:
  --base-uri           the base uri, if empty `http://127.0.0.1:8081` is assumed
  --package-key        the site-package, if empty the default site package is used
  --report             the reports to generate seperated by comma, possible keys are 'browser', 'CI' and 'json'

配置

生成的Backstop配置通过Settings.yaml和 fusion 原型的@styleguide.options.backtop注解进行配置。

Settings.yaml

Sitegeist:
  Monocle:
    BackstopJS:

      # if enabled only prototypes that have @styleguide.options.backstop.default = true will
      # be included, by default all prototypes from the styleguide are included
      defaultOptIn: false

      # if enabled only propSets from prototypes that have @styleguide.options.backstop.propSets = true
      # will be included, by default all propSets from the styleguide are included
      propSetOptIn: false

      # if enabled only useCases from prototypes that have @styleguide.options.backstop.useCases = true
      # will be included, by default all useCases from the styleguide are included
      useCaseOptIn: false

      # template for the generated backstop.json file
      # the keys 'id','viewports','scenarios' and 'pathes' are
      # replaced by the backstop:configuration command
      # all other keys can be adjusted as needed 
      # See: https://github.com/garris/BackstopJS/blob/master/README.md
      configurationTemplate: ...

      # template for each scenario, the keys 'label' and 'url' are replaced 
      # by the backstop:configuration command, everything else can be adjusted as needed  
      # See: https://github.com/garris/BackstopJS/blob/master/README.md#advanced-scenarios
      scenarioTemplate: ...

所有设置都可以为每个站点包覆盖，以适应多站点环境

Sitegeist:
  Monocle:
    packages:
      'Vendor.Site':
        BackstopJS:
          configurationTemplate:
            paths:
              bitmaps_reference: 'DistributionPackages/Vendor.Site/Test/BackstopJS/References'
              engine_scripts: 'DistributionPackages/Vendor.Site/Test/BackstopJS/EngineScripts'
              bitmaps_test: 'Data/Temporary/BackstopJS/Vendor.Site/Test'
              html_report: 'Data/Temporary/BackstopJS/Vendor.Site/HtmlReport'
              ci_report: 'Data/Temporary/BackstopJS/Vendor.Site/CiReport'

Prototype.fusion

prototype(Vendor.Site:Component) < prototype(Neos.Fusion:Component) {
    @styleguide {
        options {
            backstop {

                # enable or disable proptype the default depends on
                # the `itemOptIn` setting
                default = true

                # enable or disable the propSet inclusion, the default
                # depends on `propSetOptIn` settings   
                propSets = true

                # enable or disable the useCases inclusion, the default
                # depends on `useCaseOptIn` settings   
                useCases = true
                
                # configure scenario settings 
                scenario {
                  delay = 2000
                  hoverSelector = '.button'
                }
            }
        }
    }
}

高级场景

BackstopJS提供了一些设置来调整特定场景，具体文档见https://github.com/garris/BackstopJS#advanced-scenarios。虽然可以通过Settings.yaml调整通用场景模板，但每个原型的场景配置可以通过 fusion 注解@styleguide.options.backstop.scenario进行调整。此处定义的所有键都将覆盖生成的场景。

常见问题和解决方案

图片的延迟加载

如果项目中使用的图片使用了延迟加载，那么在截图之前，图片可能无法可靠地加载。这可以通过在风格指南中禁用延迟加载来减轻。

以下 fusion 代码通过FlowContext Development/VisualRegressionTesting 包含了禁用 Sitegeist.Kaleidoscope 和 Sitegeist.Lazybones 的延迟加载。

//
// Disable lazy loading via loading="lazy" from Sitegeist.Kaleidoscope
//
prototype(Sitegeist.Kaleidoscope:Image) {
    loading.@process.override = 'eager'
}
prototype(Sitegeist.Kaleidoscope:Picture) {
    loading.@process.override = 'eager'
}

//
// Disable lazy loading via lazysizes.js from Sitegeist.Lazybones
// 
prototype(Sitegeist.Lazybones:Image) {
    lazy.@process.override = false
}
prototype(Sitegeist.Lazybones:Picture) {
    lazy.@process.override = false
}

!!! 不要将此代码包含在开发或生产中的常规 fusion 代码中 !!!

或者，您也可以使用以下选项

在设置中配置延迟 Sitegeist.Monocle.BackstopJS.scenarioTemplate.delay: 3000
为特定原型配置延迟 @styleguide.options.backstop.scenario.delay = 3000
在设置 Sitegeist.Monocle.BackstopJS.configurationTemplate.onBeforeScript 中配置一个 onBeforeScript，确保响应式图片已加载。请参阅 https://github.com/garris/BackstopJS#running-custom-scripts。

跨平台渲染不一致性

由于不同操作系统之间渲染（尤其是字体渲染）存在细微差异，因此始终在非常相似的环境中运行测试以避免错误至关重要。BackstopJS 提供了 --docker 选项，该选项将使用在 Linux 上运行的无头 Chrome 的 docker 容器执行所有测试。

如果使用 --docker 选项，请确保使用可以由 docker 容器解析的 --base-uri 调用 ./flow backstop:configuration 命令，如下例所示。

./flow backstop:configuration --base-uri http://host.docker.internal:8081 > backstop.json && backstop test --config=backstop.json --docker

当使用 ./flow server 运行时，请使用 http 而不是 https。
Backstop docker 容器可能不知道本地主机名，无法生成开发 nginx 容器的 http 端口。

贡献

我们非常愿意接受贡献。请将您的 pull request 发送给我们。

sitegeist / monocle-backstopjs

维护者

详细信息