From 7a8a3a30d7e42984b0c8eb2667d993496b8ec980 Mon Sep 17 00:00:00 2001 From: Thierry Moisan Date: Mon, 22 Apr 2019 19:08:34 -0400 Subject: [PATCH] docs/Formula-Cookbook: add more details to tests --- docs/Formula-Cookbook.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index 57b32e295dfbb..e38c7d80b9894 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -257,7 +257,25 @@ function. The environment variable `HOME` is set to [`testpath`](https://rubydoc We want tests that don't require any user input and test the basic functionality of the application. For example `foo build-foo input.foo` is a good test and (despite their widespread use) `foo --version` and `foo --help` are bad tests. However, a bad test is better than no test at all. -See [`cmake`](https://github.com/Homebrew/homebrew-core/blob/master/Formula/cmake.rb) for an example of a formula with a good test. The formula writes a basic `CMakeLists.txt` file into the test directory then calls CMake to generate Makefiles. This test checks that CMake doesn't e.g. segfault during basic operation. Another good example is [`tinyxml2`](https://github.com/Homebrew/homebrew-core/blob/master/Formula/tinyxml2.rb), which writes a small C++ source file into the test directory, compiles and links it against the tinyxml2 library and finally checks that the resulting program runs successfully. +See [`cmake`](https://github.com/Homebrew/homebrew-core/blob/master/Formula/cmake.rb) for an example of a formula with a good test. The formula writes a basic `CMakeLists.txt` file into the test directory then calls CMake to generate Makefiles. This test checks that CMake doesn't e.g. segfault during basic operation. + +You can check that the output is as expected with `assert_equal` or `assert_match` on the output of shell_output such as in this example from the [envv formula](https://github.com/Homebrew/homebrew-core/blob/master/Formula/envv.rb): + +```ruby +assert_equal "mylist=A:C; export mylist", shell_output("#{bin}/envv del mylist B").strip +``` + +You can also check that an output file was created: + +```ruby +assert_predicate testpath/"output.txt", :exist? +``` + +Some advice for specific cases: +* If the formula is a library, compile and run some simple code that links against it. It could be taken from upstream's documentation / source examples. +A good example is [`tinyxml2`](https://github.com/Homebrew/homebrew-core/blob/master/Formula/tinyxml2.rb), which writes a small C++ source file into the test directory, compiles and links it against the tinyxml2 library and finally checks that the resulting program runs successfully. +* If the formula is for a GUI program, try to find some function that runs as command-line only, like a format conversion, reading or displaying a config file, etc. +* If the software cannot function without credentials or requires a virtual machine, docker instance, etc. to run, a test could be to try to connect with invalid credentials (or without credentials) and confirm that it fails as expected. ### Manuals