Add BINDGEN_OVERWRITE_EXPECTED for recording tests

Currently when tests are run all expectations are overwritten.
This makes it hard to debug a failing test, as every time one
reruns `cargo test` the expectation is updated and subsequently passes.

With this change we now check the `BINDGEN_OVERWRITE_EXPECTED`
env variable. If set, we overwrite the expectation. If not,
the contents stay the same and the test continues to fail.

CONTRIBUTING.md

@@ -118,6 +118,13 @@ $ cargo test
 As long as you aren't making any changes to `bindgen`'s output, running this
 should be sufficient to test your local modifications.
 
+You may set the `BINDGEN_OVERWRITE_EXPECTED` environment variable to overwrite
+the expected bindings with `bindgen`'s current output:
+
+```
+$BINDGEN_OVERWRITE_EXPECTED=1 cargo test
+```
+
 ### Testing Generated Bindings
 
 If your local changes are introducing expected modifications in the

build.rs

@@ -56,7 +56,7 @@ mod testgen {
                         dst,
                         "test_header!(header_{}, {:?});",
                         func,
-                        entry.path()
+                        entry.path(),
                     ).unwrap();
                 }
                 _ => {}

tests/expectations/tests/enum.rs

@@ -1,6 +1,11 @@
 /* automatically generated by rust-bindgen */
 
-#![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
+#![allow(
+    dead_code,
+    non_snake_case,
+    non_camel_case_types,
+    non_upper_case_globals
+)]
 
 #[repr(u32)]
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]

tests/tests.rs

@@ -4,6 +4,7 @@ extern crate bindgen;
 extern crate shlex;
 
 use bindgen::{Builder, builder, clang_version};
+use std::env;
 use std::fs;
 use std::io::{self, BufRead, BufReader, Error, ErrorKind, Read, Write};
 use std::path::PathBuf;
@@ -14,6 +15,9 @@ use std::sync::{Once, ONCE_INIT};
 mod options;
 use options::builder_from_flags;
 
+/// The environment variable that determines if test expectations are overwritten.
+static OVERWRITE_ENV_VAR: &str = "BINDGEN_OVERWRITE_EXPECTED";
+
 // Run `rustfmt` on the given source string and return a tuple of the formatted
 // bindings, and rustfmt's stderr.
 fn rustfmt(source: String) -> (String, String) {
@@ -197,8 +201,8 @@ fn compare_generated_header(
         }
     }
 
-    // Override the diff.
-    {
+    // Overwrite the expectation with actual output.
+    if env::var_os(OVERWRITE_ENV_VAR).is_some() {
         let mut expectation_file = fs::File::create(&expectation)?;
         expectation_file.write_all(actual.as_bytes())?;
     }