diff --git a/contrib/npm/README.md b/contrib/npm/README.md index 19376c22a..6508c1e8e 100644 --- a/contrib/npm/README.md +++ b/contrib/npm/README.md @@ -1,89 +1,14 @@ -# Hurl +# Hurl on npm -Hurl is a command line tool written in Rust that runs HTTP requests defined in a simple plain text format. +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 fetching data and testing HTTP 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 test HTTP responses. -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 REST / JSON apis - -```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 HTML content - -```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 - -## Samples - -See \ No newline at end of file +[distributed on npm]: https://www.npmjs.com/package/@orangeopensource/hurl \ No newline at end of file diff --git a/contrib/npm/hurl/README.md b/contrib/npm/hurl/README.md new file mode 100644 index 000000000..19376c22a --- /dev/null +++ b/contrib/npm/hurl/README.md @@ -0,0 +1,89 @@ +# Hurl + +Hurl is a command line tool written in Rust that runs HTTP requests defined in a simple plain text format. + +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 fetching data and testing HTTP 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 test HTTP responses. +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 REST / JSON apis + +```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 HTML content + +```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 + +## Samples + +See \ No newline at end of file diff --git a/contrib/npm/archive.js b/contrib/npm/hurl/archive.js similarity index 100% rename from contrib/npm/archive.js rename to contrib/npm/hurl/archive.js diff --git a/contrib/npm/bin.js b/contrib/npm/hurl/bin.js similarity index 100% rename from contrib/npm/bin.js rename to contrib/npm/hurl/bin.js diff --git a/contrib/npm/docs/hurl.1 b/contrib/npm/hurl/docs/hurl.1 similarity index 80% rename from contrib/npm/docs/hurl.1 rename to contrib/npm/hurl/docs/hurl.1 index 45e34797a..faabbaa3e 100644 --- a/contrib/npm/docs/hurl.1 +++ b/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,12 +100,29 @@ 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 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 " @@ -158,7 +178,7 @@ Follow redirect. You can limit the amount of redirects to follow by using the \ .IP "--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 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 " @@ -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 " -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 diff --git a/contrib/npm/docs/hurlfmt.1 b/contrib/npm/hurl/docs/hurlfmt.1 similarity index 96% rename from contrib/npm/docs/hurlfmt.1 rename to contrib/npm/hurl/docs/hurlfmt.1 index 8ec7c21f6..835a3180c 100644 --- a/contrib/npm/docs/hurlfmt.1 +++ b/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 diff --git a/contrib/npm/hurl.js b/contrib/npm/hurl/hurl.js similarity index 100% rename from contrib/npm/hurl.js rename to contrib/npm/hurl/hurl.js diff --git a/contrib/npm/hurlfmt.js b/contrib/npm/hurl/hurlfmt.js similarity index 100% rename from contrib/npm/hurlfmt.js rename to contrib/npm/hurl/hurlfmt.js diff --git a/contrib/npm/install.js b/contrib/npm/hurl/install.js similarity index 100% rename from contrib/npm/install.js rename to contrib/npm/hurl/install.js diff --git a/contrib/npm/package-lock.json b/contrib/npm/hurl/package-lock.json similarity index 100% rename from contrib/npm/package-lock.json rename to contrib/npm/hurl/package-lock.json diff --git a/contrib/npm/package.json b/contrib/npm/hurl/package.json similarity index 100% rename from contrib/npm/package.json rename to contrib/npm/hurl/package.json diff --git a/contrib/npm/platform.json b/contrib/npm/hurl/platform.json similarity index 100% rename from contrib/npm/platform.json rename to contrib/npm/hurl/platform.json