Begin documenting npm distribution.

contrib/npm/README.md

@@ -1,89 +1,14 @@
-# Hurl
+# Hurl on npm
 
-Hurl is a command line tool written in Rust that runs <b>HTTP requests</b> defined in a simple <b>plain text format</b>.
+Hurl is [distributed on npm] as a thin wrapper around the native binary.
 
-The `@orangeopensource/hurl` package allows JavaScript developers to use Hurl in npm scripts.
+## Build
 
-Hurl can perform requests, capture values and evaluate queries on headers and body response. Hurl is very
-versatile: it can be used for both <b>fetching data</b> and <b>testing HTTP</b> sessions.
-
-
-```hurl
-# Get home:
-GET https://example.net
-
-HTTP/1.1 200
-[Captures]
-csrf_token: xpath "string(//meta[@name='_csrf_token']/@content)"
-
-# Do login!
-POST https://example.net/login?user=toto&password=1234
-X-CSRF-TOKEN: {{csrf_token}}
-
-HTTP/1.1 302
-```
-
-Hurl can run HTTP requests but can also be used to <b>test HTTP responses</b>.
-Different types of queries and predicates are supported, from [XPath](https://en.wikipedia.org/wiki/XPath) and 
-[JSONPath](https://goessner.net/articles/JsonPath/) on body response, to assert on status code and response headers.
-
-It is well adapted for <b>REST / JSON apis</b>
-
-```hurl
-POST https://api.example.net/tests
-{
-    "id": "4568",
-    "evaluate": true
-}
-
-HTTP/1.1 200
-[Asserts]
-header "X-Frame-Options" == "SAMEORIGIN"
-jsonpath "$.status" == "RUNNING"    # Check the status code
-jsonpath "$.tests" count == 25      # Check the number of items
-jsonpath "$.id" matches /\d{4}/     # Check the format of the id
-```
-
-and <b>HTML content</b>
-
-```hurl
-GET https://example.net
-
-HTTP/1.1 200
-[Asserts]
-xpath "normalize-space(//head/title)" == "Hello world!"
-```
-
-## Installation
+## Publish
 
 ```
-npm install --save-dev @orangeopensource/hurl
-```
-
-This will download the appropriate Hurl binaries for your platform. `hurlmft` binary is also installed, which 
-you can use for [exporting Hurl files to JSON files](https://hurl.dev/docs/frequently-asked-questions.html#how-can-i-use-my-hurl-files-outside-hurl). 
-
-
-## Usage
-
-In your `package.json` file:
-
-```
-{
-  "name": "sample-app",
-  "scripts": {
-    "test": "hurl --test --glob test/*.hurl",
-    ...
-  },
-  ...
+$ cp docs/man/*.1 contrib/npm/hurl/docs/
 ```
 
 
-
-## Documentation
-
-See <https://hurl.dev>
-
-## Samples
-
-See <https://hurl.dev/docs/samples.html>
+[distributed on npm]: https://www.npmjs.com/package/@orangeopensource/hurl

contrib/npm/hurl/README.md

@@ -0,0 +1,89 @@
+# Hurl
+
+Hurl is a command line tool written in Rust that runs <b>HTTP requests</b> defined in a simple <b>plain text format</b>.
+
+The `@orangeopensource/hurl` package allows JavaScript developers to use Hurl in npm scripts.
+
+Hurl can perform requests, capture values and evaluate queries on headers and body response. Hurl is very
+versatile: it can be used for both <b>fetching data</b> and <b>testing HTTP</b> sessions.
+
+
+```hurl
+# Get home:
+GET https://example.net
+
+HTTP/1.1 200
+[Captures]
+csrf_token: xpath "string(//meta[@name='_csrf_token']/@content)"
+
+# Do login!
+POST https://example.net/login?user=toto&password=1234
+X-CSRF-TOKEN: {{csrf_token}}
+
+HTTP/1.1 302
+```
+
+Hurl can run HTTP requests but can also be used to <b>test HTTP responses</b>.
+Different types of queries and predicates are supported, from [XPath](https://en.wikipedia.org/wiki/XPath) and 
+[JSONPath](https://goessner.net/articles/JsonPath/) on body response, to assert on status code and response headers.
+
+It is well adapted for <b>REST / JSON apis</b>
+
+```hurl
+POST https://api.example.net/tests
+{
+    "id": "4568",
+    "evaluate": true
+}
+
+HTTP/1.1 200
+[Asserts]
+header "X-Frame-Options" == "SAMEORIGIN"
+jsonpath "$.status" == "RUNNING"    # Check the status code
+jsonpath "$.tests" count == 25      # Check the number of items
+jsonpath "$.id" matches /\d{4}/     # Check the format of the id
+```
+
+and <b>HTML content</b>
+
+```hurl
+GET https://example.net
+
+HTTP/1.1 200
+[Asserts]
+xpath "normalize-space(//head/title)" == "Hello world!"
+```
+
+## Installation
+
+```
+npm install --save-dev @orangeopensource/hurl
+```
+
+This will download the appropriate Hurl binaries for your platform. `hurlmft` binary is also installed, which 
+you can use for [exporting Hurl files to JSON files](https://hurl.dev/docs/frequently-asked-questions.html#how-can-i-use-my-hurl-files-outside-hurl). 
+
+
+## Usage
+
+In your `package.json` file:
+
+```
+{
+  "name": "sample-app",
+  "scripts": {
+    "test": "hurl --test --glob test/*.hurl",
+    ...
+  },
+  ...
+```
+
+
+
+## Documentation
+
+See <https://hurl.dev>
+
+## Samples
+
+See <https://hurl.dev/docs/samples.html>

contrib/npm/hurl/docs/hurl.1

@@ -1,4 +1,4 @@
-.TH hurl 1 "15 Feb 2022" "hurl 1.7.0-snapshot" " Hurl Manual"
+.TH hurl 1 "17 Aug 2022" "hurl 1.7.0-snapshot" " Hurl Manual"
 .SH NAME
 
 hurl - run and test HTTP requests.
@@ -19,7 +19,7 @@ Hurl is very versatile, it enables to chain HTTP requests, capture values from H
 
     $ hurl session.hurl
 
-If no input-files are specified, input is read from stdin.
+If no input files are specified, input is read from stdin.
 
     $ echo GET http://httpbin.org/get | hurl
         {
@@ -37,14 +37,15 @@ If no input-files are specified, input is read from stdin.
         }
 
 
-Output goes to stdout by default. For output to a file, use the -o option:
+Output goes to stdout by default. For output to a file, use the \fI-o, --output\fP option:
 
     $ hurl -o output input.hurl
 
-
-
 By default, Hurl executes all HTTP requests and outputs the response body of the last HTTP call.
 
+To have a test oriented output, you can use \fI--test\fP option:
+
+    $ hurl --test *.hurl
 
 
 .SH HURL FILE FORMAT
@@ -53,8 +54,8 @@ The Hurl file format is fully documented in \fIhttps://hurl.dev/docs/hurl-file.h
 
 It consists of one or several HTTP requests
 
-    GET http:/example.net/endpoint1
-    GET http:/example.net/endpoint2
+    GET http:/example.org/endpoint1
+    GET http:/example.org/endpoint2
 
 
 .IP "Capturing values"
@@ -63,16 +64,18 @@ A value from an HTTP response can be-reused for successive HTTP requests.
 
 A typical example occurs with csrf tokens.
 
-    GET https://example.net
+    GET https://example.org
     HTTP/1.1 200
     # Capture the CSRF token value from html body.
     [Captures]
     csrf_token: xpath "normalize-space(//meta[@name='_csrf_token']/@content)"
 
     # Do the login !
-    POST https://example.net/login?user=toto&password=1234
+    POST https://example.org/login?user=toto&password=1234
     X-CSRF-TOKEN: {{csrf_token}}
 
+More information on captures here \fIhttps://hurl.dev/docs/capturing-response.html\fP
+
 .IP "Asserts"
 
 The HTTP response defined in the Hurl session are used to make asserts.
@@ -97,13 +100,30 @@ You can also include explicit asserts combining query and predicate
 
 Thanks to asserts, Hurl can be used as a testing tool to run scenarii.
 
-
-
+More information on asserts here \fIhttps://hurl.dev/docs/asserting-response.html\fP
 
 .SH OPTIONS
 
 Options that exist in curl have exactly the same semantic. 
 
+Options specified on the command line are defined for every Hurl file's entry.
+
+For instance:
+
+    $ hurl --location foo.hurl
+
+will follow redirection for each entry in `foo.hurl`. You can also define option only for a particular entry with an `[Options]` section. For instance, this Hurl file:
+
+    GET https://google.com
+    HTTP/* 301
+
+    GET https://google.com
+    [Options]
+    location: true
+    HTTP/* 200
+
+will follow redirection only for the second entry.
+
 .IP "--cacert "
 
 Tells curl to use the specified certificate file to verify the peer.
@@ -158,7 +178,7 @@ Follow redirect.  You can limit the amount of redirects to follow by using the \
 
 .IP "--glob <glob> "
 
-Specify input files that match the given blob.
+Specify input files that match the given glob pattern.
 
 Multiple glob flags may be used. This flag supports common Unix glob patterns like *, ? and []. 
 However, to avoid your shell accidentally expanding glob patterns before Hurl handles them, you must use single quotes or double quotes around each pattern.
@@ -197,7 +217,7 @@ See also \fI--connect-timeout\fP option.
 
 .IP "--no-color "
 
-Do not colorize Output
+Do not colorize output
 
 .IP "--no-output "
 
@@ -216,6 +236,8 @@ Write output to <file> instead of stdout.
 
 Print filename and status for each test (on stderr)
 
+Deprecated, use \fI--test\fP or \fI--json\fP instead.
+
 .IP "-x, --proxy [protocol://]host[:port] "
 
 Use the specified proxy.
@@ -236,9 +258,11 @@ If the HTML report already exists, it will be updated with the new test results.
 
 Print test metrics at the end of the run (on stderr)
 
+Deprecated, use \fI--test\fP or \fI--json\fP instead.
+
 .IP "--test "
 
-Activate test mode; equals \fI--no-output](#no-output) [--progress](#progress) [--summary\fP
+Activate test mode: the HTTP response is not outputted anymore, progress is reported for each Hurl file tested and a text summary is displayed when all files have been run. 
 
 .IP "--to-entry <entry-number> "
 
@@ -267,7 +291,7 @@ Note that defining a variable twice produces an error.
 
 .IP "-v, --verbose "
 
-Turn on verbose output on standard error stream
+Turn on verbose output on standard error stream.
 Useful for debugging.
 
 A line starting with '>' means data sent by Hurl.
@@ -276,6 +300,13 @@ A line starting with '*' means additional info provided by Hurl.
 
 If you only want HTTP headers in the output, -i, --include might be the option you're looking for.
 
+.IP "--very-verbose "
+
+Turn on more verbose output on standard error stream.
+
+In contrast to  \fI--verbose\fP option, this option outputs the full HTTP body request and response on standard error.
+
+
 .IP "-h, --help "
 
 Usage help. This lists all current command line options with a short description.
@@ -304,11 +335,15 @@ Sets the proxy server to use if no protocol-specific proxy is set.
 
 .IP "no_proxy <comma-separated list of hosts>"
 
-list of host names that shouldn't go through any proxy.
+List of host names that shouldn't go through any proxy.
 
 .IP "HURL_name value"
 
-Define variable (name/value) to be used in Hurl templates. This is similar than \fI--variable](#variable) and [--variables-file\fP options.
+Define variable (name/value) to be used in Hurl templates. This is similar than \fI--variable\fP and \fI--variables-file\fP options.
+
+.IP "NO_COLOR"
+
+When set to a non-empty string, do not colorize output (see \fI--no-color\fP option).
 
 .SH EXIT CODES
 

contrib/npm/hurl/docs/hurlfmt.1

@@ -1,4 +1,4 @@
-.TH hurl 1 "15 Feb 2022" "hurl 1.7.0-snapshot" " Hurl Manual"
+.TH hurl 1 "17 Aug 2022" "hurl 1.7.0-snapshot" " Hurl Manual"
 .SH NAME
 
 hurlfmt - format Hurl files