Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/cosimo/http-cuke

Cucumber-style HTTP frontends testing
https://github.com/cosimo/http-cuke

cucumber http perl testing testing-tools

Last synced: about 2 months ago
JSON representation

Cucumber-style HTTP frontends testing

Host: GitHub
URL: https://github.com/cosimo/http-cuke
Owner: cosimo
Created: 2012-01-23T17:53:39.000Z (almost 13 years ago)
Default Branch: master
Last Pushed: 2020-02-28T13:58:14.000Z (almost 5 years ago)
Last Synced: 2023-04-21T10:38:24.672Z (over 1 year ago)
Topics: cucumber, http, perl, testing, testing-tools
Language: Perl
Homepage:
Size: 53.7 KB
Stars: 9
Watchers: 2
Forks: 2
Open Issues: 0
Metadata Files:
- Readme: README.pod

Awesome Lists containing this project

README

=head1 NAME

http-cuke - Cucumber-style HTTP configuration testing for the masses

=head1 SYNOPSIS

Example of test scenario:

Feature: Front page responds correctly
In order to avoid problems with caching logic and/or frontend configuration
As an operations ninja
I want to check that front page is served correctly and the frontends configuration is correct

Scenario: HTTP to HTTPS redirects are in place
When I go to "http://my.example.server.lan/"
Then I should be redirected to "https://my.example.server.lan/"
Then the final HTTP status code should be "200"

Put that text in a C file, and point
C to the directory that contains it with:

http-cuke --test-dir ./some-tests

Or run just a single test file:

http-cuke --test ./single.test

Have a look at the C directory where you will
find this example:

Feature: Google front page allows me to search
In order not to be stuck without being able to google something
As a curious person
I want to be check that Google is available

Scenario: Google frontpage is available
Given the HTTP request header "Accept-Language" is "en"
When I go to "http://www.google.com/"
Then the final HTTP status code should be "200"
Then the page should contain "Google"

This is a test you can actually run with:

cd bin
./http-cuke --test ../tests/example.test

You can also use B in your test files.
See the L chapter.

=head1 DESCRIPTION

Run cucumber style tests against any HTTP server.

If you are not familiar with cucumber, check it out
at L.

With this tool you can define set of tests (or B
and B in cucumber-speak) and run them.

The type of tests that C can help you with
are those that involve checking a HTTP server configuration,
behavior or plain responses.

You can check redirects, response headers, cookies,
response bodies, inject custom HTTP headers in the requests,
check Varnish responses, and more.

=head1 OTHER SUPPORTED OPTIONS

=over

=item C<--allow-insecure-ssl>

When this option is specified, C will silently connect to HTTPS hosts
B. This is B, so only
do it if you are aware of the implications.

The typical use case is to connect to individual backends part of a bigger
cluster typically behind a load balancer.

=item C<--useragent-timeout>

How long should the user agent that makes the requests wait for backend
requests. This is using C, so don't expect perfect control
of client timeout. For example, this will usually not include eventual DNS
timeouts/slowdowns, so the actual timeout might be much longer than you
specify.

Usage:

http-cuke --useragent-timeout 10 --test ...

=item C<--useragent-string>

Override the default user agent string (C).

Usage:

http-cuke --useragent-string 'MyWebSiteTesterFTW/0.01'

=back

=head1 MOTIVATION: THE WHY

This tool is B meant to replace tools like C or similar
ones. It is meant to perform automated testing for frontends configuration
testing.

By frontend I mean Apache, Nginx, Varnish, and deadly combinations of the
three. It can be a nightmare to make sure you have all the correct redirects in
place, that pages are cached according to your own logic, etc...

Yes, but even then, after all, cucumber is pretty well established.
So why?

Because of the dependencies mess. I don't want to depend on too many packages,
and Perl already has all the tools I needed to do this. I just glued them
together, and there you have a TAP-compliant cucumber-style HTTP testing that
can easily be hooked up to B, B or your preferred CI/CD
system.

The B is that it opens up even complex HTTP
testing to a broader audience, not necessarily programmers. That is, btw, a
major point of BDD testing, and that's Good(tm).

=head1 VARIABLES SUPPORT

Here's an example of test script in Cucumber style:

Feature: My service can be monitored correctly by Nagios
In order to make sure that Nagios alerts don't fire unnecessarily
As an operations ninja
I want to verify that the resources accessed by Nagios are always available

Scenario: ping.html page is served over http
When I go to "http://my.server.local/ping.html"
Then the final HTTP status code should be "200"
Then the page should contain "I am alive"

It is possible (and desirable) to embed variables in your test files.
In the example above, instead of hardcoding the C
address, you can use a variable like this:

Scenario: ping.html page is served over http
When I go to "{{ SERVER_URL }}/ping.html"
Then the final HTTP status code should be "200"
Then the page should contain "I am alive"

To run this test, you need to invoke C with the C<-D>
option, to define variables. Example:

http-cuke --test ./nagios.test -D SERVER_URL=http://my.server.local

If you use variables in your test scripts, but omit to declare them
when invoking C, you will be warned with a message:

Undefined variable 'SERVER_URL' in line:

When I go to "{{ SERVER_URL }}/ping.html"

=head1 AVAILABLE TESTS

So what are the B that are available to build
the test cases?

Here's a list:

=over 4

=item C

A super-cheap hack, but it works for now. Examples:

When I send a GET request to "http://somedomain.lan/"
When I send a POST request to "http://somedomain.lan/" with body ""
When I send a PATCH request to "http://somedomain.lan/some-api" with body "{"hello":"there"}"

=item C

In this case, the specified external script, which must be executable,
will be invoked with the content of the downloaded document as STDIN stream.

The script must exit with code zero (e.g. C) if the document is valid.
Any other exit code will be interpreted as if the document failed validation.

=item C

=back

=head1 AUTHOR

Cosimo Streppone, C

=head1 LICENSE AND COPYRIGHT

This code is offered under the Open Source BSD license.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

=over 4

=item *

Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.

=item *

Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.

=item *

Neither the name of Opera Software, Kahoot! AS nor the names of its contributors
may be used to endorse or promote products derived from this software without
specific prior written permission.

=back

=head1 DISCLAIMER OF WARRANTY

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.