README.md
1# httpUnit
2
3httpUnit tests web and net servers for basic functionality.
4
5The tool can open an http/https connection and verify that the expected
6status code is received. It can also verify that the resulting HTML output
7contains a string or regular expression. It can direct the request to a
8particular IP address, ignoring DNS (similar to `curl --resolve`). The tool
9can also open a TCP connection and verify that the connection was completed.
10For https connections it will output various TLS-related information.
11
12Tests can be input three ways:
13
14 * *Command line:* A single test can be listed on the command line. This is useful for interactive debugging.
15 * *TOML file:* A list of tests, with a full range of features, can be listed in a TOML file. This is the recommended mode for tests done on a regular basis. The format is described below.
16 * *JSON/Hiera mode:* A simple list tcp tests can be specified in JSON format. These are in the format of a iptables "set". This mode is highly specific to a local requirement.
17
18When specifying a single test on the command line, the only tests performed
19are status code, and regex. If url does not contain a scheme ("https://",
20"http://"), "http://" is prefixed. The IP may be an empty string to indicate
21all IP addresses resolved to from the URL's hostname.
22
23Usage:
24
25 httpUnit [flag] [-hiera="path/to/sets.json"] [-toml="/path/to/httpunit.toml"] [url] [ip] [code] [regex]
26
27The flags are:
28
29 -filter=""
30 if specified, only uses this IP address; may end with "." to
31 filter by IPs that start with the filter
32 -no10=false
33 no RFC1918 addresses
34 -timeout="3s"
35 connection timeout
36 -tags=""
37 if specified, only runs plans that are tagged with one of the
38 tags specified. You can specify more than one tag, seperated by commas
39 -protos=""
40 if specified, only runs plans where the URL contains the given
41 protocol. Valid protocols are: http,https,tcp,tcp4,tcp6,udp,udp4,udp6,ip,ip4,ip6
42 You can specify more than one protocol, seperated by commas
43 -header="X-Request-Guid"
44 in more verbose mode, print this HTTP header
45 -v
46 verbose output: show successes
47 -vv
48 more verbose output: show -header, cert details
49
50### URLs
51
52URLs may be specified with various protocols: http, https, tcp,
53udp, ip. "4" or "6" may be appended to tcp, udp, and ip (as per
54[net/#Dial](http://golang.org/pkg/net/#Dial])). tcp and udp must specify
55a port, or default to 0. http and https may specify a port to override
56the default.
57
58### TOML
59
60The [toml file](https://github.com/toml-lang/toml) has two sections:
61`Plan` is a list of test plans.
62`IPs` are a table of search and replace regexes.
63
64Each `[[plan]]` lists:
65
66 * `label =` A label for documentation purposes. It must be unique.
67 * `url =` The URL to retrieve.
68 * `ips =` For http/https, a list of IPs to send the URL to. Default is "use DNS". Otherwise the connection is made to the IP address listed, ignoring DNS.
69 * `code =` For http/https, the expected status code, default 200.
70 * `string =` For http/https, a string we expect to find in the result.
71 * `regex =` For http/https, a regular expression we expect to match in the result.
72 * `timeout =` An optional timeout for the test in seconds. Default is 3 seconds.
73 * `tags =` An optional set of tags for the test. Used for when you want to only run a subset of tests with the `-tags` flag
74 * `insecureSkipVerify = true` Will allow testing of untrusted or self-signed certificates.
75
76
77The test plan is run once for each item in the ips list, or more if macros
78are in effect.
79
80In the `ips` list, `*` will be substituted by all the A and AAAA records
81returned when DNS is performed on the hostname of the URL.
82
83The `[[IPs]]` section is for defining macros. Here are some typical use-cases:
84
85Specify a value _n_ to mean "10.0.0.n". This may save you a lot of typing
86in a big configuration file:
87
88 '^(\d+)$' = ["10.0.0.$1"]
89
90Similar to the previous example, but specify a base address:
91
92 BASEIP = ["10.0.0."]
93 '^(\d+)$' = ["BASEIP$1"]
94
95Specify a value _n_ to mean the 16th IP address many CIDR bocks:
96
97 '^(\d+)$' = ["10.0.0.$1", "10.1.1.$1", "10.2.2.$1", "10.3.3.$1", "10.4.4.$1"]
98
99Specify a value _nINT_ to mean .n and .n+64, plus the whatever DNS returns:
100
101 BASEIP = ["10.0.0."]
102 '^(\d+)$' = ["BASEIP$1", "BASEIP($1+64)", "*"]
103
104## Why we made this?
105
106This tool makes it easy to do test-driven development on your web server.
107
108Every request to our web server passes through three systems that are all
109complex and error prone: the firewall, the load balancer, and the web server
110itself. Even when running in a test environment with automated tools that
111generate the configurations we still needed a way to test our results.
112
113Before this tool each change was followed by a few simple manual tests,
114often by manually typing `curl` commands. We missed a lot of errors.
115
116With this tool, we now have hundreds of tests that we can run with a single
117command. The tests run in parallel therefore all the testing is done very
118quickly.
119
120When we need to make a change we first add the test, then we proceed making
121the change until the test passes. This test-driven development has accumulated
122200 tests that we run for any change, considerably more than we'd ever run
123manual. This improves confidence in our ability to make changes quickly.
124
125While making unrelated changes we often run it in a loop to make sure we
126don't unintentionally break anything.
127
128The command-line mode has been useful both in development of changes, and
129diagnosing outages.
130
131## A simple example file:
132
133 # Verify that this URL returns text that matches "some regex":
134 [[plan]]
135 label = "api"
136 url = "http://api.example.com/"
137 text = "API for example.com"
138 regex = "some regex"
139
140 # Verify that this URL returns a redirect. Send to both
141 # the IP address listed in DNS, plus 10.11.22.33 and 10.99.88.77.
142 [[plan]]
143 label = "redirect"
144 url = "https://example.com/redirect"
145 ips = ["*", "10.11.22.33", "10.99.88.77"]
146 code = 301
147
148## A more complex example file:
149
150In this example we want an IP address to mean the IP address, but if we
151specify a single number (e.g. "16") we want that to expand to the .16 address
152of a few different CIDR blocks. We also want to be able to specify a number +
153INT (e.g. "16INT") to indicate a slightly different list.
154
155 [IPs]
156 BASEIP = ["87.65.43."]
157 '^(\d+)$' = ["*", "BASEIP$1", "BASEIP($1+64)", "1.2.3.$1"]
158 '^(\d+)INT$' = ["10.0.1.$1", "10.0.2.$1", "BASEIP$1", "BASEIP($1+64)"]
159
160 [[plan]]
161 label = "api"
162 url = "http://api.example.com/"
163 # This will generate the DNS A/AAAA records, 87.65.43.16, 87.65.43.80, 1.2.3.16 and 8.7.6.5:
164 ips = ["16", "8.7.6.5"]
165 text = "API for example.com"
166 regex = "some regex"
167 tags = ["apis","example.com"]
168
169 [[plan]]
170 label = "redirect"
171 url = "https://example.com/redirect"
172 # This will generate the DNS A/AAAA records, 10.0.1.20, 10.0.2.20, 87.65.43.20, 87.65.43.84:
173 ips = ["*", "20INT"]
174 code = 301
175 tags = ["redirect","example.com"]
176
177 [[plan]]
178 label = "mail"
179 url = "tcp://mail-host.com:25"
180