From fcfc9f4dc604e2f981a403c2d0895e8109fa03db Mon Sep 17 00:00:00 2001
From: Glyn Normington <normingtong@vmware.com>
Date: Tue, 29 Sep 2020 10:07:47 +0100
Subject: [PATCH] Add dev guide

Remove the VERBOSE flag from the tests and use built-in cargo facilities to
handle verbose output instead.

Improve the formatting of verbose test output.
---
 CONTRIBUTING.md |  4 +++
 DEVELOPING.md   | 90 +++++++++++++++++++++++++++++++++++++++++++++++++
 README.md       |  6 +++-
 tests/cts.rs    | 11 +++---
 4 files changed, 106 insertions(+), 5 deletions(-)
 create mode 100644 DEVELOPING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 59448b6..efa10e1 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -23,6 +23,10 @@ git commit -a
 git push origin my-new-feature
 ```
 
+See the [Developer Guide](./DEVELOPING.md) for how to set up a development environment and run the tests.
+If you want to make a small change, e.g. to fix a typo, you don't have to set up a development environment
+as the tests will run automatically against any pull request. 
+
 ### Staying In Sync With Upstream
 
 When your branch gets out of sync with the jsonpath-standard/jsonpath-reference-implementation/main branch, use the following to update:
diff --git a/DEVELOPING.md b/DEVELOPING.md
new file mode 100644
index 0000000..6d00eb4
--- /dev/null
+++ b/DEVELOPING.md
@@ -0,0 +1,90 @@
+# Developing jsonpath-reference-implementation
+
+This guide describes how to set up a development environment and run the tests.
+If you'd like to submit changes, see the [Contributor Guide](./CONTRIBUTING.md).
+
+## Setting up a development environment
+
+The reference implementation is written in [Rust](https://www.rust-lang.org/).
+
+### Installing Rust
+
+Install the latest stable version of Rust by following [these instructions](https://rustup.rs/).
+This will also install [Cargo](https://doc.rust-lang.org/book/ch01-03-hello-cargo.html) which is Rust's
+build system and package manager.
+
+If you are new to Rust, check out the resources at [Learn Rust](https://www.rust-lang.org/learn).
+
+## Running the Compliance Test Suite
+
+Once Rust is installed, run the Compliance Test Suite on the command line by changing directory to
+a clone of this repository and issuing:
+```
+cargo test
+```
+
+If all goes well, the output should include this:
+```
+...
+test tests::compliance_test_suite ... ok
+
+test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
+...
+```
+
+## Debugging test failures
+
+To run a test on its own, edit [cts.json](tests/cts.json) and set the `focus` property of the relevant
+test to `true`, for example:
+<pre>
+  }, {
+    "name": "wildcarded child",
+    <b>"focus": true,</b>
+    "selector": "$.*",
+    "document": {"a" : "A", "b" : "B"},
+    "result": ["A", "B"]
+  }, {
+</pre>
+
+When one or more tests are focussed in this way, the test suite will fail with the message
+"testcase(s) still focussed" even if all the tests pass.
+This prevents pull requests being merged in which tests are accidentally left focussed.
+
+To see details of which tests run, use:
+```
+cargo test -- --show-output
+```
+
+If you want a bit more detail of what Cargo is doing, use:
+```
+cargo test -v
+```
+
+## Editing
+
+First class Rust support is available in various editors. See [Rust Tools](https://www.rust-lang.org/tools)
+for details.
+
+## Code formatting and linting
+
+To format the code, issue:
+```
+cargo fmt
+```
+
+To check the code for stylistic and other problems (known as "linting"), issue:
+```
+cargo clippy
+```
+
+The following one-liner formats/lints the code and, if that was successful, runs the tests:
+```
+cargo fmt && cargo clippy && cargo test
+```
+
+## Generating the docs
+
+To generate and view the docs, issue:
+```
+cargo doc --document-private-items --open
+```
diff --git a/README.md b/README.md
index 3e405b4..56dc99a 100644
--- a/README.md
+++ b/README.md
@@ -2,4 +2,8 @@
 
 **WORK IN PROGRESS**
 
-See [cts.json](tests/cts.json) for the Compliance Test Suite and [grammar.pest](src/grammar.pest) for the Parsing Expression Grammar of the Reference Implementation.
\ No newline at end of file
+This Reference Implementation follows, and usually lags behind, the [internet draft](https://jsonpath-standard.github.io/internet-draft/).
+
+See [cts.json](tests/cts.json) for the Compliance Test Suite and [grammar.pest](src/grammar.pest) for the Parsing Expression Grammar of the Reference Implementation.
+
+See the [Developer Guide](./DEVELOPING.md) if you want to run the code against the test suite. See the [Contributor Guide](./CONTRIBUTING.md) if you'd like to submit changes.  
\ No newline at end of file
diff --git a/tests/cts.rs b/tests/cts.rs
index 65b09af..30b5de9 100644
--- a/tests/cts.rs
+++ b/tests/cts.rs
@@ -11,8 +11,6 @@ mod tests {
     use std::fs;
     use std::panic;
 
-    const VERBOSE: bool = false;
-
     #[derive(Debug, PartialEq, Serialize, Deserialize)]
     struct TestSuite {
         tests: Vec<Testcase>,
@@ -51,9 +49,14 @@ mod tests {
                 continue;
             }
             let result = panic::catch_unwind(|| {
-                if VERBOSE {
+                if t.invalid_selector {
+                    println!(
+                        "testcase name = `{}`, selector = `{}`, expected invalid selector.",
+                        t.name, t.selector
+                    );
+                } else {
                     println!(
-                        "name = {}, selector = {}, document = {:?}, result = {:?}",
+                        "testcase name = `{}`, selector = `{}`, document:\n{:#}\nexpected result = `{}`.",
                         t.name, t.selector, t.document, t.result
                     );
                 }