Usage instructions and basic usage example

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+* examples and usage instructions
+
 ### Fixed
 
 ### Changed

README.md

@@ -1,14 +1,31 @@
-A stable version of compiletest-rs
+A test runner that builds tests with rustc or cargo (or any other compiler
+with some configuration effort) and compares the output of the compiler with
+a file that you check into git. This allows you to test how your libraries
+show up to your users when the library is used wrongly and emits errors.
 
-## Magic behavior
+## Usage
+
+See [examples directory](examples) for how to use this in your own crate.
+To be able to use it with `cargo test`, you need to put
+
+```toml
+[[test]]
+name = "your_test_file"
+harness = false
+```
+
+into your `Cargo.toml`, otherwise `cargo test` will only look for `#[test]`s and
+not run your `fn main()` that actually executes `ui_test`
+
+## Implicit (and possibly surprising) behavior
 
 * Tests are run in order of their filenames (files first, then recursing into folders).
   So if you have any slow tests, prepend them with a small integral number to make them get run first, taking advantage of parallelism as much as possible (instead of waiting for the slow tests at the end).
 * `cargo test --test your_test_name -- --help` lists the commands you can specify for filtering, blessing and making your tests less verbose.
     * Since `cargo test` on its own runs all tests, using `cargo test -- --check` will not work on its own, but `cargo test -- --quiet` and `cargo test -- some_test_name` will work just fine, as the CLI matches.
 * if there is a `.stdin` file with the same filename as your test, it will be piped as standard input to your program.
 
-## Supported magic comment annotations
+## Supported comment annotations
 
 If your test tests for failure, you need to add a `//~` annotation where the error is happening
 to ensure that the test will always keep failing at the annotated line. These comments can take two forms:

examples/rustc_basic.rs

@@ -0,0 +1,8 @@
+use ui_test::{run_tests, Config};
+
+fn main() -> ui_test::color_eyre::Result<()> {
+    // Compile all `.rs` files in the given directory (relative to your
+    // Cargo.toml) and compare their output against the corresponding
+    // `.stderr` files.
+    run_tests(Config::rustc("examples_tests/rustc_basic"))
+}

examples_tests/rustc_basic/hello.rs

@@ -0,0 +1,4 @@
+fn main() {
+    println("hello world")
+    //~^ ERROR: expected function, found macro `println`
+}

examples_tests/rustc_basic/hello.stderr

@@ -0,0 +1,14 @@
+error[E0423]: expected function, found macro `println`
+ --> examples_tests/rustc_basic/hello.rs:2:5
+  |
+2 |     println("hello world")
+  |     ^^^^^^^ not a function
+  |
+help: use `!` to invoke the macro
+  |
+2 |     println!("hello world")
+  |            +
+
+error: aborting due to 1 previous error
+
+For more information about this error, try `rustc --explain E0423`.