Python HTTP automated testing facility
Project description
py-http-auto-test: Python HTTP automated testing facility
What's this?
This is a simple HTTP testing library for Python.
The main idea is to be able to write simple YAML files that describe a suite of HTTP tests, and then run them either as a standalone script or as a pytest test suite, with the provided conftest.py plugin.
A YAML test suite might look like this:
base_url: https://mysite.example.com
tests:
- url: "/"
description: "Fetch the index page"
match:
status: 200
body:
- "<!DOCTYPE html>"
- url: "/favicon.ico"
description: "Ensure the favicon file is present and served with the correct content type"
match:
headers:
- "content-type: image/x-icon"
status: 200
- ...
Why?
Once upon a time, there was http-cuke which I made as an attempt to free myself of having to write tests. At that time, people believed that BDD/cucumber would enable not-necessarily technical people to write business logic test suites. I have personally never seen this happen.
Instead of making the same mistake again, and learning from the past years of experience testing systems, I tried to write something that:
- makes use of a solid HTTP library: libcurl, pycurl
- covers websockets testing. pycurl doesn't yet
- minimizes the amount of code one needs to write to run a test suite
Some Use-Cases
- When building a new package image/AMI, it's nice to be able to spawn a new instance and get a simple and clear answer to the question: Can I online this instance? Will things work?
- Regression testing a web application
- Live testing of a running system every x minutes
Requirements
See the requirements.txt file for the full list of requirements. The main ones are:
- Python 3.8 or later
- The
libcurl4-openssl-devpackage on Debian-based systems, orlibcurl-develor whatever the equivalent on your system is, required to buildpycurl pycurlversion 7+websocketslibrary to run tests against websockets
Optional Requirements
pytestif you want to run http tests as a pytest test suite
Installation
sudo apt-get update -qq
# You need libcurl to build and install pycurl
sudo apt-get install -y libcurl4-openssl-dev
pip install --upgrade py-http-auto-test
Usage
There are two main ways to use this library:
- standalone
- pytest
Standalone
This distribution provides a http-test-runner.py script (usually installed in /usr/local/bin, or in your virtualenv's bin folder) that can be used to run one or more YAML test files.
Examples:
http-test-runner.py --help
http-test-runner.py --test-file website.yaml
# Run the tests but against an alternative IP address
# (this is similar to `MAP * <ip>` in Chrome or `--connect-to *:*:<ip>` in curl)
http-test-runner.py --test-file website.yaml --target-host 127.0.0.1
The library also supports template variables in the YAML files. This is useful if you want to define a set of tests for your web application, and then run them against different environments, for example:
---
# YAML test file
base_url: "https://{{ hostname }}"
tests:
- url: "/"
description: "Index page exists and it's served correctly"
...
and then:
http-test-runner.py --test-file website.yaml --var "hostname=test.mydomain.com"
The {{ hostname }} variable will be replaced with test.mydomain.com in the test suite.
The template format is jinja2.
pytest
All that was described for the standalone case works also as a pytest test suite. You need to make sure the provided conftest.py plugin is found when you run pytest.
Example:
pytest -v ./test.yaml
If you need to pass on arguments or template variables, you can do so using environment variables prefixed with the string HTTPTEST_, as in:
HTTPTEST_TARGET_HOST="127.0.0.1" HTTPTEST_TEMPLATE_VARS="hostname=test.mydomain.com" pytest -v ./test.yaml
To pass on multiple environment variables, use a space character to separate multiple values, as in:
HTTPTEST_TARGET_HOST="127.0.0.1" HTTPTEST_TEMPLATE_VARS="hostname=test.mydomain.com protocol=https" pytest -v ./test.yaml
Comprehensive Example of a Single Test
An HTTP test has a bunch of attributes, some of which are optional. The following is a semi-complete example:
- url: "/index.html"
description: "Verify that we can correctly download the index page as gzip-compressed response"
headers:
- "accept: text/html"
- "accept-encoding: gzip"
http2: true # false (http/1.1) is the default
# Skip a temporarily failing test by adding the `skip` attribute
skip: true # false is the default
# Output the request and response dump with the test outcome
verbose: true # false is the default
# Here is where you specify the test requirements
match:
# Response HTTP status must be 200 for the test to pass
# This can also be a list of status codes
status: 200
# Verify that the response matches the following headers.
# Header names will be matched regardless of upper or lower case.
headers:
- "content-type: text/html"
- "content-encoding: gzip"
# Verify that the response body contains the specified string patterns
body:
- "<!DOCTYPE html>"
- "<h1>Hello</h1>"
# Verify that the request took less than 500ms
timing: 500ms
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file py-http-auto-test-1.0.16.tar.gz.
File metadata
- Download URL: py-http-auto-test-1.0.16.tar.gz
- Upload date:
- Size: 15.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.3
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 487fe6c17a49f76978760382dae8146e2c8196cd384415c59457f78796032ca9 |
|
| MD5 | 10c840fd7398452a2b1363bd43c21f64 |
|
| BLAKE2b-256 | 372b8e7c446e46fc54fa98c26e5fa495664d41b1956ee9f91c187d149931835f |
File details
Details for the file py_http_auto_test-1.0.16-py3-none-any.whl.
File metadata
- Download URL: py_http_auto_test-1.0.16-py3-none-any.whl
- Upload date:
- Size: 14.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.3
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 1ec3f5ca33ad8b1f46edc2cc1035678ee2d87c296f0363ae05b94623c5bd09a6 |
|
| MD5 | 64eee36a64816e261c187ed6f28ca540 |
|
| BLAKE2b-256 | 19cae0a8d480a2a83a9c36012e7593a026bf2a2566960503579c8bd8ffb1586e |
