f10d23e893
This is a new testsuite intended to replace the other tests, which provides an easy facility to update tests, validate output, and more.
43 lines
2.8 KiB
Markdown
43 lines
2.8 KiB
Markdown
# Testsuite
|
|
|
|
## Introduction
|
|
|
|
This is the main testsuite for exercising all functionality of mdBook.
|
|
|
|
Tests should be organized into modules based around major features. Tests should use `BookTest` to drive the test. `BookTest` will set up a temp directory, and provides a variety of methods to help create a build books.
|
|
|
|
## Basic structure of a test
|
|
|
|
Using `BookTest`, you typically use it to copy a directory into a temp directory, and then run mdbook commands in that temp directory. You can run the `mdbook` executable, or use the mdbook API to perform whatever tasks you need. Running the executable has the benefit of being able to validate the console output.
|
|
|
|
See `build::basic_build` for a simple test example. I recommend reviewing the methods on `BookTest` to learn more, and reviewing some of the existing tests to get a feel for how they are structured.
|
|
|
|
For example, let's say you are creating a new theme test. In the `testsuite/theme` directory, create a new directory with the book source that you want to exercise. At a minimum, this needs a `src/SUMMARY.md`, but often you'll also want `book.toml`. Then, in `testsuite/theme.rs`, add a test with `BookTest::from_dir("theme/mytest")`, and then use the methods to perform whatever actions you want.
|
|
|
|
`BookTest` is designed to be able to chain a series of actions. For example, you can do something like:
|
|
|
|
```rust
|
|
BookTest::from_dir("theme/mytest")
|
|
.build()
|
|
.check_main_file("book/index.html", str![["file contents"]])
|
|
.change_file("src/index.md", "new contents")
|
|
.build()
|
|
.check_main_file("book/index.html", str![["new contents"]]);
|
|
```
|
|
|
|
## Snapbox
|
|
|
|
The testsuite uses [`snapbox`] to drive most of the tests. This library provides the ability to compare strings using a variety of methods. These strings are written in the source code using either the [`str!`] or [`file!`] macros.
|
|
|
|
The magic is that you can set the `SNAPSHOTS=overwrite` environment variable, and snapbox will automatically update the strings contents of `str!`, or the file contents of `file!`. This makes it easier to update tests. Snapbox provides nice diffing output, and quite a few other features.
|
|
|
|
Expected contents can have wildcards like `...` (matches any lines) or `[..]` (matches any characters on a line). See [snapbox filters] for more info and other filters.
|
|
|
|
Typically when writing a test, I'll just start with an empty `str!` or `file!`, and let snapbox fill it in. Then I review the contents to make sure they are what I expect.
|
|
|
|
Note that there is some normalization applied to the strings. See `book_test::assert` for how some of these normalizations happen.
|
|
|
|
[`snapbox`]: https://docs.rs/snapbox/latest/snapbox/
|
|
[`str!`]: https://docs.rs/snapbox/latest/snapbox/macro.str.html
|
|
[`file!`]: https://docs.rs/snapbox/latest/snapbox/macro.file.html
|
|
[snapbox filters]: https://docs.rs/snapbox/latest/snapbox/assert/struct.Assert.html#method.eq
|