PerfDocs

PerfDocs 是一种工具，用于检查所有性能测试是否在代码树中进行了文档记录。

目前，它仅用于此文档验证，但将来它还将根据这些描述自动生成文档，这些文档将显示在源文档页面中（而不是维基，这些文档目前位于维基中）。

本地运行

可以使用 mach 运行 PerfDocs 的 mozlint 集成。

$ mach lint --linter perfdocs .

可以通过包含 --fix 标志来重新生成性能测试的文档。

$ mach lint --linter perfdocs . --fix

配置

此代码风格检查工具没有可用的配置选项。它扫描 testing 下的完整源代码树，查找名为 perfdocs 的文件夹，验证其内容，并重新生成文档（如果提供了 --fix）。这已针对所有性能测试工具实现，生成的文档将显示在 性能测试 中。

在 perfdocs 文件夹中，需要有一个 index.rst 文件，并且它需要在文件中的某个位置包含字符串 {documentation}，测试文档将放置在此处。这些文件夹还必须具有一个遵循此模式的 config.yml 文件。

CONFIG_SCHEMA = {
    "definitions": {
        "metrics_schema": {
            "metric_name": {
                "type": "object",
                "properties": {
                    "aliases": {"type": "array", "items": {"type": "string"}},
                    "description": {"type": "string"},
                    "matcher": {"type": "string"},
                },
                "required": ["description", "aliases"],
            },
        },
    },
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "manifest": {"type": "string"},
        "static-only": {"type": "boolean"},
        "metrics": {"$ref": "#/definitions/metrics_schema"},
        "suites": {
            "type": "object",
            "properties": {
                "suite_name": {
                    "type": "object",
                    "properties": {
                        "tests": {
                            "type": "object",
                            "properties": {
                                "test_name": {"type": "string"},
                            },
                        },
                        "description": {"type": "string"},
                        "owner": {"type": "string"},
                    },
                    "required": ["description"],
                }
            },
        },
    },
    "required": ["name", "manifest", "static-only", "suites"],
}

以下是 Raptor 框架的配置文件示例。

name: raptor
manifest: testing/raptor/raptor/raptor.toml
suites:
    desktop:
        description: "Desktop tests."
        tests:
            raptor-tp6: "Raptor TP6 tests."
    mobile:
        description: "Mobile tests"
    benchmarks:
        description: "Benchmark tests."
        tests:
            wasm: "All wasm tests."

生成警报的指标也可以这样记录。

name: raptor
manifest: testing/raptor/raptor/raptor.toml
metrics:
    "First Paint":
        description: "The description of the metric."
        aliases:
            - fcp
            - anAliasForFCP
        # Optional regex to match the metrics found in the tests with this
        # documented metric
        matcher: f.*
suites:
    desktop:
        description: "Desktop tests."
        tests:
            raptor-tp6: "Raptor TP6 tests."
    mobile:
        description: "Mobile tests"
    benchmarks:
        description: "Benchmark tests."
        tests:
            wasm: "All wasm tests."

已记录的指标必须存在于套件的测试中。如果不存在，则验证将失败。如果测试中的指标未记录，则情况相同。此外，如果定义了 metrics，则期望在给定套件的 perfdocs 文件夹中找到 metrics.rst 文件。它必须包含字符串 {metrics_documentation}，文档应添加到此处。 metrics.rst 在生成的文件夹中重命名为 {suite-name}-metrics.rst，因此，如果需要在 index.rst 文件中链接到它，它应该包含一个 {metrics_rst_name} 字符串，用于链接应添加的位置 - 预计它将在 toctree 部分中找到。

请注意，需要为正在记录的框架实现一个 FrameworkGatherer，因为它们各自可能具有不同的解析测试清单以获取测试的方法。请参阅 RaptorGatherer，以了解为 Raptor 实现的收集器示例。

来源