DOCSEARCHbyAlgolia
Submit Docs

Hurl

repository·master·Indexed 12 days ago

https://github.com/orange-opensource/hurl

A command-line tool for running and testing HTTP requests defined in a simple plain-text format. It supports data fetching, complex request chaining, and assertions for REST, GraphQL, SOAP, and HTML APIs.

Tokens
184.2K
Snippets
626
Records
861
Agent score
92%

What's inside Hurl

  1. Overview of Hurl features and capabilities

    master

    Hurl is an HTTP testing tool powered by libcurl. It allows you to:

    • Define HTTP requests and responses in a human-readable file format.
    • Capture values from responses (headers, body, status, etc.) to use in subsequent requests.
    • Assert conditions on responses (status codes, body content, headers, etc.) to validate API behavior.
    • Run tests and generate various report formats like HTML, JSON, JUnit, and TAP.
    • Use variables and templates to make tests dynamic and reusable.

  2. What is Hurl?

    master

    Hurl is a command-line tool used to run HTTP requests defined in a simple plain text format. It is designed for both fetching data and testing HTTP sessions. Key capabilities include:

    • Chaining Requests: Execute multiple requests in sequence.
    • Capturing Values: Extract data from responses (e.g., using XPath) to use in subsequent requests.
    • Evaluating Queries: Assert against response headers, status codes, and bodies (JSON, XML, HTML).
    • Versatility: Supports REST, SOAP, GraphQL, and standard HTML/XML/JSON APIs.
    • Performance Testing: Assert on response duration and file integrity (e.g., SHA256 hashes).
    • CI/CD Integration: Supports multiple report formats including text, JUnit, TAP, and HTML.

  3. Overview of Hurl's capabilities and structure

    master

    Hurl is an HTTP testing tool powered by libcurl. It allows you to define HTTP requests and responses in a specific file format to automate testing and data retrieval.

    Key features include:

    • HTTP Testing: Assert status codes, headers, and body content (JSON, XML, HTML, etc.).
    • Data Capture: Extract values from responses (headers, cookies, JSONPath, XPath, Regex) to use in subsequent requests.
    • Templating: Use variables and functions to make requests dynamic.
    • Reporting: Generate test results in multiple formats including HTML, JSON, JUnit, and TAP.

  6. What is Hurl and how does it differ from curl and Karate?

    master

    Hurl is a command-line tool focused on the HTTP protocol. Unlike GUI-oriented tools like Postman, Hurl is designed for local use and CI/CD pipelines. It uses a simple, text-based file format that can serve as both executable tests and documentation.

    Key distinctions:

    • Vs. curl: While curl is used for single requests, Hurl can chain multiple requests together using [Captures] to inject data from one response into a subsequent request, and it includes built-in [Asserts] to test responses.
    • Vs. Karate: Hurl is more lightweight and focused strictly on the HTTP domain. It does not include a JavaScript runtime or a headless browser, making it more reliable and faster for testing backend endpoints without the complexity of DOM management.
    • Vs. Selenium: Because Hurl works on raw HTTP data rather than a browser engine, it has a much lower probability of false positives in integration tests.

  7. Overview of the Hurl file format

    master

    A Hurl file is a collection of Entries. Each entry consists of a Request followed by one or more Responses.

    Within a response, you can perform two main actions:

    1. Capturing: Extracting data from the response (e.g., status codes, headers, body content, JSONPath, XPath, or Regex) into variables.
    2. Asserting: Validating that the response meets specific criteria (e.g., status code, headers, body content, or specific data types).

    Variables captured in one request can be used in subsequent requests within the same file or via the --variable and --variables-file CLI options.

  8. Understand the structure of a Hurl file

    master

    A Hurl file is composed of a list of entries. Each entry must contain a mandatory request. An entry may optionally be followed by a response section.

    Responses are used to:

    1. Capture values from the HTTP response to be used in subsequent requests.
    2. Add asserts to validate the HTTP response (e.g., status codes, headers, or body content).

    A file containing only requests is valid.

    # Request
GET https://acmecorp.net

# Optional Response
HTTP 200
[Asserts]
xpath "normalize-space(//head/title)" == "Hello world!"

  9. Understand Hurl's data types and lexical rules

    master

    Hurl uses specific lexical rules to parse values in its files. Understanding these helps in correctly formatting variables, JSON values, and predicates.

    • Booleans and Nulls: Supports true, false, and null.
    • Numbers:
      • integer: A sequence of one or more digits.
      • float: An integer followed by a dot and one or more digits.
      • number: Either an integer or a float.
    • Hexadecimal: hexdigit represents a single character in the range [0-9A-Fa-f].
    • Scientific Notation: exponent follows the pattern (e|E)(+|-)?[0-9]+ (e.g., e+10, E-5).

  10. Configure HTTP Request Bodies

    master

    The request body must be the last part of the request. Hurl supports several ways to define bodies:

    • JSON: Use a literal JSON block. When using this, Content-Type: application/json is automatically set. Supports Hurl variables.
    • XML: Use a literal XML block. Note: The succinct XML syntax does not support variables; use a multiline string with xml identifier if variables are needed.
    • GraphQL: Use a multiline string with the graphql identifier. Supports both Hurl and GraphQL variables.
    • Multiline String: Use triple backticks (```). Can use language hints (e.g., ```json) to set Content-Type.
    • Oneline String: Use single backticks (`) for text without newlines.
    • Binary Data: Use base64, or hex, prefixes followed by a ;.
    • File: Use file,path; to include the contents of a local file.
    # JSON Body
POST https://example.org/api/dogs
{
    "id": 0,
    "name": "Frieda"
}

# GraphQL Body
POST https://example.org/starwars/graphql
```graphql
{
  human(id: "{{human_id}}") {
    name
  }
}

    Binary File Body

    POST https://example.org file,data.bin;

  11. Manage cookie storage and sessions

    master

    By default, requests within the same Hurl file share a cookie store, which allows you to simulate session-based scenarios (e.g., logging in with one request and using the resulting cookie in the next).

    To disable shared cookie storage and treat every request as having no cookies, use the CLI option:

    • --no-cookie-store

  12. Use curl-compatible options in Hurl

    master

    Hurl supports options that have the exact same semantics as curl. These can be applied globally to all entries in a file via the command line, or scoped to specific requests using an [Options] section within the .hurl file.

    Example of scoping an option (like --location to follow redirects) to only one specific request in a file:

    GET https://example.org
HTTP 301

GET https://example.org
[Options]
location: true
HTTP 200