Begin documenting npm distribution.

This commit is contained in:
jcamiel 2022-08-20 14:38:31 +02:00
parent fdc8255a7e
commit 07266aa399
No known key found for this signature in database
GPG Key ID: 07FF11CFD55356CC
12 changed files with 149 additions and 100 deletions

View File

@ -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 ## Publish
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 $ cp docs/man/*.1 contrib/npm/hurl/docs/
```
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",
...
},
...
``` ```
[distributed on npm]: https://www.npmjs.com/package/@orangeopensource/hurl
## Documentation
See <https://hurl.dev>
## Samples
See <https://hurl.dev/docs/samples.html>

View File

@ -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>

View File

@ -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 .SH NAME
hurl - run and test HTTP requests. 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 $ 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 $ 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 $ hurl -o output input.hurl
By default, Hurl executes all HTTP requests and outputs the response body of the last HTTP call. 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 .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 It consists of one or several HTTP requests
GET http:/example.net/endpoint1 GET http:/example.org/endpoint1
GET http:/example.net/endpoint2 GET http:/example.org/endpoint2
.IP "Capturing values" .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. A typical example occurs with csrf tokens.
GET https://example.net GET https://example.org
HTTP/1.1 200 HTTP/1.1 200
# Capture the CSRF token value from html body. # Capture the CSRF token value from html body.
[Captures] [Captures]
csrf_token: xpath "normalize-space(//meta[@name='_csrf_token']/@content)" csrf_token: xpath "normalize-space(//meta[@name='_csrf_token']/@content)"
# Do the login ! # 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}} X-CSRF-TOKEN: {{csrf_token}}
More information on captures here \fIhttps://hurl.dev/docs/capturing-response.html\fP
.IP "Asserts" .IP "Asserts"
The HTTP response defined in the Hurl session are used to make 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. 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 .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 " .IP "--cacert "
Tells curl to use the specified certificate file to verify the peer. 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> " .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 []. 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. 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 " .IP "--no-color "
Do not colorize Output Do not colorize output
.IP "--no-output " .IP "--no-output "
@ -216,6 +236,8 @@ Write output to <file> instead of stdout.
Print filename and status for each test (on stderr) 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] " .IP "-x, --proxy [protocol://]host[:port] "
Use the specified proxy. 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) Print test metrics at the end of the run (on stderr)
Deprecated, use \fI--test\fP or \fI--json\fP instead.
.IP "--test " .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> " .IP "--to-entry <entry-number> "
@ -267,7 +291,7 @@ Note that defining a variable twice produces an error.
.IP "-v, --verbose " .IP "-v, --verbose "
Turn on verbose output on standard error stream Turn on verbose output on standard error stream.
Useful for debugging. Useful for debugging.
A line starting with '>' means data sent by Hurl. 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. 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 " .IP "-h, --help "
Usage help. This lists all current command line options with a short description. 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>" .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" .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 .SH EXIT CODES

View File

@ -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 .SH NAME
hurlfmt - format Hurl files hurlfmt - format Hurl files