7bdea7c085
This fixes a problem where custom preprocessors were not being registered when running tests. This was caused by the test function rebuilding the preprocessor map. This removes the code that was rebuilding the preprocessors and removing the IndexPreprocessor when running tests. Skipping IndexPreprocessor was added back in https://github.com/rust-lang/mdBook/pull/741 to fix https://github.com/rust-lang/mdBook/issues/724 which was caused by https://github.com/rust-lang/mdBook/pull/685 which added the IndexPreprocessor. Additionally, https://github.com/rust-lang/mdBook/pull/1986 added running *all* preprocessors. The IndexPreprocessor was removed because in the past the code was testing against the source directly, and the path from `chapter.path` is the converted `index.md` file, and that filename does not exist in the source. This isn't a problem anymore because due to https://github.com/rust-lang/mdBook/pull/891 it is not reading from the `src` directory. Note that this results in a minor change where the chapter path changes from `README.md` to `index.md` in the output and the `--chapter` option. I think I'm ok with that change, though it would be easy to switch it back if that's an issue.
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:
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.