mantra

Manuels ANforderungs-TRAcing (或 MANaged TRAcing)

mantra 是一个用于更容易地在需求、实现和测试之间进行跟踪的工具。

查看 使用示例 文件夹，了解如何使用 mantra 进行需求跟踪。

核心概念

使用 ID 来标识需求，并在实现和/或测试中引用它们。这些需求 ID 必须在实现和测试端手动设置。mantra 然后将可用的需求和找到的跟踪添加到 SQL 数据库中进行进一步分析。

使用跟踪信息，可以将测试代码覆盖率传递给 mantra 以获取需求覆盖率信息。

需求 ID

每个需求都必须有一个唯一的需求 ID。可以通过使用父 ID 作为前缀后跟 . 来创建需求层次结构。

示例

req_id

req_id.sub_req_id

需求跟踪

要获取需求跟踪，可以在系统/项目的实现和/或测试中引用 ID。需求 ID 的引用方式在不同编程语言之间可能不同。如果未为文件类型定义特殊语法，则默认为搜索具有以下形式的引用：[req(<requirement id(s)>)]。

特定语言跟踪

• Rust：使用 mantra-rust-trace 收集需求跟踪

  将 mantra-rust-macros 添加到依赖项，使用属性宏 req 或类似函数宏 reqcov 创建需求跟踪。

  示例

  use mantra_rust_macros::{req, reqcov};
  
  #[req(req_id)]
  fn some_fn() {
    reqcov!(function_like_trace);
  }
  

用法

通过 CLI

mantra 可以通过 cargo install mantra 安装。

所有信息都存储在SQL数据库中，并且可以在使用任何命令之前通过 url 设置连接。默认情况下，URL是 sqlite://mantra.db?mode=rwc。

注意： 目前仅支持SQLite，因为一些SQL查询包含SQLite特定的语法。

• 一次性收集所有数据

  mantra collect[<文件路径>]

  这将在指定的路径中查找TOML文件。默认情况下，路径设置为 mantra.toml。

  文件结构

  # Collect requirements from local Markdown files.
  #
  # **Note:** Only one option to collect requirements may be given.
  [requirements.from-wiki]
  
  # Root path to start looking for requirements.
  # Empty means current directory.
  root = ""
  
  # Base URL for all requirements
  link = "https://github.com/mhatzl/mantra-wiki/tree/main/5-Requirements/"
  
  
  # Collect requirements from a JSON file adhering to the `RequirementSchema`.
  #
  # **Note:** Only one option to collect requirements may be given.
  [requirements.from-schema]
  
  # The path to a JSON file containing requirements.
  filepath = "requirements.json"
  
  
  # Collect traces from local files
  #
  # **Note:** Only one option to collect traces may be given.
  [traces.from-source]
  
  # Root path to start looking for traces.
  # Empty means current directory.
  root = ""
  
  # If 'false', the filepath will be stored relativ to the root path.
  keep-path-absolute = false
  
  
  # Collect traces from a JSON file adhering to the `TraceSchema`.
  #
  # **Note:** Only one option to collect traces may be given.
  [trace.from-schema]
  
  # The path to a JSON file containing traces.
  filepath = "traces.json"
  
  
  # Collect coverage from a JSON file adhering to the `CoverageSchema`.
  [coverage]
  
  # Path to a JSON file containing coverage.
  filepath = "coverage.json"
  
  
  # Collect reviews from TOML files adhering to the `ReviewSchema`.
  [reviews]
  
  # List of review files to add.
  files = ["first_review.toml"]
  

• 生成报告

  mantra report--格式=HTML,JSON<文件路径>

  这将在指定的文件路径创建HTML和JSON报告。可选地，可以通过 --template 提供模板文件。模板可以使用 Tera 模板语言。JSON格式传递给模板。如果没有提供模板，则使用 report_default_template。

  为了渲染自定义数据，如需求信息和测试运行元数据，可以将 --info-template 和 --test-run-template 参数设置为模板文件。然后使用 Tera 预渲染这些模板，并将渲染内容作为 rendered_info 和 rendered_meta 提供给常规的 info 和 meta 字段。

  可以使用 --project_name、--project_version 和 --project_link 参数设置项目名称、版本和链接。也可以使用 --tag-name 和 --tag-link 参数设置标签名称和链接。标签应用于指示报告生成时使用的需求快照/标签。

• 从本地Markdown文件添加需求

  mantra requirements from-wiki<root> <link>

  root 参数必须指向一个包含需求的现有文件/文件夹。 link 是需求的基本URL。

  有关如何在Markdown文件中定义需求的说明，请参阅 mantra wiki 中的 req(extract.wiki)。

  此命令 不会 删除数据库中已存储的需求。使用 生成 计数器来检测现有需求是否未包含在最新的 提取 中。

  使用 mantra delete-old 删除最新调用中未添加/更新的所有需求。

• 从本地源添加跟踪

  mantra trace from-source[--keep-path-absolute] <root>

  root 参数必须指向一个文件或文件夹，用于在文本文件中搜索跟踪。默认情况下，跟踪的文件路径作为相对于给定根的相对路径添加。这可以通过设置 --keep-path-absolute 来更改。

• 添加覆盖率

  由于测试的覆盖率输出高度依赖于语言和工具，因此 mantra 仅提供通过遵循 RequirementSchema 的文件添加覆盖率数据。

  mantra coverage--data-file<路径到JSONfile>

• 添加评论

  mantra review<reviews>

  可以提供一个或多个指向 mantra 评论的文件路径。

  注意： 目前仅支持TOML作为评论格式。

  文件结构

  name = <review name>
  date = <yyyy-mm-dd HH:MM[optional [:SS.fraction]]>
  reviewer = <reviewer of this review>
  comment = <general comment for this review>
  
  [[requirements]]
  id = <verified requirement ID>
  comment = <optional comment for this specific ID>
  
  [[requirements]]
  id = <verified requirement ID>
  comment = <optional comment for this specific ID>
  

许可证

MIT许可证