mirror of
https://github.com/Orange-OpenSource/hurl.git
synced 2024-12-24 03:21:40 +03:00
Begin documenting npm distribution.
This commit is contained in:
parent
fdc8255a7e
commit
07266aa399
@ -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
|
89
contrib/npm/hurl/README.md
Normal file
89
contrib/npm/hurl/README.md
Normal 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>
|
@ -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 <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
|
||||
|
@ -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
|
Loading…
Reference in New Issue
Block a user