ospec: tests and docs for o.report

ospec/README.md

@@ -311,7 +311,9 @@ ospec will automatically evaluate all `*.js` files in any folder named `/tests`.
 
 Ospec doesn't work when installed globally. Using global scripts is generally a bad idea since you can end up with different, incompatible versions of the same package installed locally and globally.
 
-To work around this limitation, you can use [`npm-run`](https://www.npmjs.com/package/npm-run) which enables one to run the binaries of locally installed packages.
+If you're using a recent version of npm (v5+), you can use run `npx ospec` from your project folder.
+
+Otherwise, to work around this limitation, you can use [`npm-run`](https://www.npmjs.com/package/npm-run) which enables one to run the binaries of locally installed packages.
 
 ```
 npm install npm-run -g
@@ -449,6 +451,13 @@ If running in Node.js, ospec will call `process.exit` after reporting
 results by default. If you specify a reporter, ospec will not do this
 and allow your reporter to respond to results in its own way.
 
+
+---
+
+### Number o.report(results)
+
+The default reporter used by `o.run()` when none are provided. Returns the number of failures, doesn't exit Node.js by itself. It expects an array of [test result data](#result-data) as argument.
+
 ---
 
 ### Function o.new()

ospec/tests/test-ospec.js

@@ -49,6 +49,42 @@ new function(o) {
 				done()
 			})
 		})
+		o("o.report() returns the number of failures", function () {
+			var log = console.log, error = console.error
+			console.log = o.spy()
+			console.error = o.spy()
+
+			function makeError(msg) {try{throw msg ? new Error(msg) : new Error} catch(e){return e}}
+			try {
+				var errCount = o.report([{pass: true}, {pass: true}])
+
+				o(errCount).equals(0)
+				o(console.log.callCount).equals(1)
+				o(console.error.callCount).equals(0)
+
+				errCount = o.report([
+					{pass: false, error: makeError("hey"), message: "hey"}
+				])
+
+				o(errCount).equals(1)
+				o(console.log.callCount).equals(2)
+				o(console.error.callCount).equals(1)
+
+				errCount = o.report([
+					{pass: false, error: makeError("hey"), message: "hey"},
+					{pass: true},
+					{pass: false, error: makeError("ho"), message: "ho"}
+				])
+				o(errCount).equals(2)
+				o(console.log.callCount).equals(3)
+				o(console.error.callCount).equals(3)
+			} catch (e) {
+				o(1).equals(0)("Error while testing the reporter")
+			}
+
+			console.log = log
+			console.error = error
+		})
 	})
 }(o)