时间戳

首页 > 解决方案 > 有没有办法构建包含测试文档字符串的 Rust 文档？

unit-testing - 有没有办法构建包含测试文档字符串的 Rust 文档？

问题描述

我们的测试方法将测试文档作为文档输出中的第一类对象。具体来说，它定义了每个行为测试所测试的规范。

在具有适当记录的测试的项目上运行cargo doc并不会产生从测试文档字符串派生的文档的方式，而且我看不到任何明显的方法可以使其在输出中包含测试文档字符串。

一个示例模块如下：

/// This function does some important stuff
pub fn working_fn() -> bool {
    true
}

#[cfg(test)]
mod tests {
    //! This is some important set of tests
    //!

    use super::*;

    /// The function should work
    #[test]
    fn it_works() {
        assert!(working_fn());
    }
}

我得到了 public 的文档输出working_fn，但没有得到tests模块的输出。我很欣赏另一个复杂性是测试是私有的，理想情况下，我能够记录私有测试而无需记录其他私有对象。

标签： unit-testingtestingrustbddrust-cargo

解决方案

您可以引入一个新功能标志，该标志可用于专门为文档目的处理测试。

将该功能添加到您的 Cargo.toml：

[features]
dox = []

在您的代码中使用功能标志。

  1. tests如果测试正在运行或提供了功能标志，则编译模块。
  2. #[test]如果未提供功能标志，则仅标记功能。该#[test]属性自动暗示#[cfg(test)]，因此我们必须跳过它以允许该函数存在。
/// This function does some important stuff
pub fn working_fn() -> bool {
    true
}

#[cfg(any(test, feature = "dox"))]
mod tests {
    //! This is some important set of tests
    //!
    use super::*;

    /// The function should work
    #[cfg_attr(not(feature = "dox"), test)]
    fn it_works() {
        assert!(working_fn());
    }
}

构建文档

cargo doc --document-private-items --features=dox

密切关注#[cfg(rustdoc)]，这将使您无需使用自己的功能标志，但目前还不稳定。

也可以看看：

理想情况下，我能够记录私有测试，而无需记录其他私有对象

您可以进行测试pub或pub(crate).

如果这不是一个选项，我认为这将比它的价值更烦人。我知道的直接解决方案是遵循如何通过条件编译更改函数的限定符？有条件地进行pub或不进行测试。

推荐阅读