Hurl is a command line tool that runs HTTP requests defined in a simple plain text format.
That sounds super useful for monitoring my various sites and projects around the Web. The tool even purports to be designed with CI/CD integration in mind.
I set it up to test the httpcat.us site I wrote about in my last post. In this post, I:
- Describe a super-simple
- Improve the
.hurlfile to check for content with asserts
- Generate HTML and a JUnit Report from
hurlvia GitLab CI
TL;DR - 🔗 The code for this project is stored at gitlab.com/brie/hurl.
A super simple
.hurl file looks something like this:
That can be built on a bit:
GET https://httpcat.us HTTP/* 200
With that content in a file like
hurl --test hello.hurl and you’ll get something like this:
hello.hurl: Running [1/1] hello.hurl: Success (1 request(s) in 103 ms) -------------------------------------------------------------------------------- Executed files: 1 Succeeded files: 1 (100.0%) Failed files: 0 (0.0%) Duration: 108 ms
In order to ensure the site is served via
hello.hurl file would look like this instead:
GET https://httpcat.us HTTP/2 200
The syntax so far is pretty intuitive:
- We’re checking that we can
- We can check for a specific version of
HTTPand confirm that the response code is
Let’s keep going. Let’s add a test for a page that should
404. To do that, the
hello.hurl file gets updated to look like this:
GET https://httpcat.us HTTP/2 200 GET https://httpcat.us/lolno HTTP/2 404
.hurl file to check for content with asserts
So far, we are checking that the site is reachable, is serving the expected version of HTTP and the desired HTTP response status code. That’s great but I want to test that the images on httpcat.us are present. We can do this by giving the appropriate XPath to
You can use Chrome Developer Tools to identify, evaluate and validate XPath values. The linked article has more but in short:
- Open Developer Tools
- In the Console tab, navigate to the desired element
- Right-click > Copy > Copy XPath
Here’s how the
hello.hurl file we have been building looks with some
GET https://httpcat.us HTTP/* 200 [Asserts] xpath "string(//head/title)" == "HTTP Status Codes -- with cats" xpath "string(//body/div/div/div/div/p/text())" contains "👋" xpath "//img" count == 6
I’ll summarize the purpose of each
xpath “string(//head/title)” == “HTTP Status Codes — with cats”
This checks to make sure that the
<title> tag is exactly
HTTP Status Codes -- with cats.
xpath “string(//body/div/div/div/div/p/text())” contains ”👋”
This checks to make sure that the selected text contains the 👋 emoji.
xpath “//img” count == 6
This checks that there are six
<img> tags on the front page. I want to make sure that each of the six cats on the home page is present. 🐱
[Asserts] section can also check response headers. These two lines can be added to the
header "Content-Type" == "text/html; charset=utf-8" header "Server" == "Google Frontend"
Let’s add in the tests for the headers and a few more tests for the
GET https://httpcat.us HTTP/* 200 [Asserts] xpath "string(//head/title)" == "HTTP Status Codes -- with cats" xpath "//img" count == 6 xpath "string(//body/div/div/div/div/p/text())" contains "👋" header "Content-Type" == "text/html; charset=utf-8" header "Server" == "Google Frontend" GET https://httpcat.us/not-found HTTP/* 404 [Asserts] header "Content-Type" == "text/html; charset=utf-8" xpath "string(//h1)" == "MEOW?" xpath "string(//h2)" == "What were you looking for?"
hello.hurl file is complete. Let’s do more with it than
hurl --test hello.hurl.
Generating HTML and JUnit Reports with
To put the HTML report in a directory called
public/ and the JUnit report file in a file called
http.xml, we’ll adjust our
hurl command to:
hurl --test --report-html public --report-junit http.xml hello.hurl
hurl via GitLab CI
.hurl file and the desired options ready, it’s time to put this all in a CI pipeline. The
.gitlab-ci.yml below will:
- Run the
- Serve the HTML report via GitLab Pages
- show the unit test reports in GitLab
pages: image: name: orangeopensource/hurl entrypoint: [""] script: - hurl --test --report-html public --report-junit http.xml *.hurl artifacts: paths: - http.xml - public/ reports: junit: http.xml
The HTML report generated by the
hello.hurl we have been building is at brie.gitlab.io/hurl.
🚀 Get started!
You can 🍴 fork the brie/hurl project to get up and running with
hurl in a CI pipeline.
In the linked project, the
.gitlab-ci.yml job is expanded to use the
services keyword. The
services keyword is used to start a Web server that the
hurl test are run against. This is useful if you don’t have a Web server to be tested ready just yet.
.gitlab-ci.yml from that project looks like this:
pages: services: - name: kennethreitz/httpbin alias: httpbin allow_failure: true image: name: orangeopensource/hurl entrypoint: [""] script: - hurl --test --report-html public --report-junit http.xml *.hurl artifacts: paths: - http.xml - public/ reports: junit: http.xml
kennethreitz/httpbin image spins up an instance of the very wonderful httpbin, a simple HTTP request and response service.
The image atop this post was generated via Midjourney with the prompt:
giant sunset featuring lemon slice sun