Awesome

Test Server Configs

Test Server Configs is a collection of test scripts for server validation.

Getting Started

This repository contains unit tests suites helping validate correctness of a server. Some steps are required to make them ready to run.

Usage

GitHub Actions

Pre-requisites

Create a workflow .yml file in your repositories .github/workflows directory. An example workflow is available below. For more information, reference the GitHub Help Documentation for Creating a workflow file.

Make sure to use the grafana/setup-k6-action action to install k6.

Inputs

See action.yml. For more information on these inputs, see the API Documentation.

Example workflow

steps:
  - uses: actions/checkout@v4
  - uses: grafana/setup-k6-action@v1
  - name: Test with server-configs-test
    uses: h5bp/server-configs-test@main
    with:
      command: test
      server: nginx
      root-path: /var/www/server.localhost
      certs-path: /etc/nginx/certs
      configs-volumes: test/vhosts:/etc/nginx/conf.d;h5bp:/etc/nginx/h5bp;nginx.conf:/etc/nginx/nginx.conf;mime.types:/etc/nginx/mime.types
      tests: basic-file-access;caching;cache-busting;custom-errors;forbidden-files;precompressed-files-gzip;rewrites;ssl

Standalone

Get the files ready by either:
- Downloading latest release build
- Generating fixtures
```
npm install
npm run build
```
Install k6
Setup the server, local or Docker
- Add these hosts:
  - server.localhost
  - www.server.localhost
  - secure.server.localhost
  - www.secure.server.localhost
- Secure secure. hosts, possibly with certs within certs/
- Mount fixtures/ to be the root of files served by the server
Run the units (see Usage)

Tests

To run all tests, execute:

$ k6 run lib/index.js

To run only specific tests, use the environment variable TESTS with all wanted test names separated by : as value.

The environment variable can be passed as an argument:

$ k6 run lib/index.js -e TESTS=basic-file-access:rewrites

`basic-file-access`

Check if all common files are served correctly.

The requested file should be served exactly as expected, all HTTP headers should be valid.

<details> <summary>References</summary>

</details>

`cache-busting`

Check if cache-busting is working.

The requests that contain a hashed-key extension prefix ([name].[hash].[ext]) should serve the target file correctly.

`concatenation`

Check if concatenation is working.

The requests for [name].combined.[ext] should be served as a concatenation of he a.[ext] and b.[ext] files.

`custom-errors`

Check if errors are served as desired.

The erroneous requests should be served with the custom document provided.

`enforce-gzip`

Check if gzip is enable even if mangled headers.

`forbidden-files`

Check if forbidden files are well handled.

The requests should be answered with 403 errors when:

The requested directory does not contain a default document (no file listing);
The requested directory is hidden (the name start with a dot);
The requested file is hidden (the name start with a dot);
The above requests are made in the .well-known directory;
The requested file is known to contain sensitive data.

<details> <summary>References</summary>

</details>

`precompressed-files-(gzip|brotli)`

Check if server use gzip/brotli precompressed-files if available.

The requests should be served with a valid gzip/brotli file if a precompressed-files is available.

`rewrites`

Check redirection behavior.

The redirection should follow the following paths:

Redirect to no-www when the host is prefixed with www. but require not to;
Redirect to www when the host is not prefixed with www. but require to;
Redirect to www/no-www whichever the connexion is secure or not.
Always redirect HTTP to HTTPS whatever is the host if secure alternatives exists;

<details> <summary>References</summary>

https://observatory.mozilla.org/faq/

</details>

`ssl`

Check correctness for the TLS/SSL configuration.

The requests should be served with:

A technically valid certificate;
A secure TLS version;
A valid and secure cipher suite;
A secure protocol (HTTP/2);
With a well formatted HSTS header.

<details> <summary>References</summary>

</details>

`benchmark`

Bonus test file to run a load benchmark. This test is not included in the run-all script. A separate command is required to run it:

$ k6 run lib/benchmark.js

Suite Structure

[
  {
    "name": "unit tests suite 1",
    "domain": "http://server.localhost/ (optional)",
    "default": { // optional default values
      "requestHeaders": {
        "Header-Name": "header to add to all the requests"
      },
      "responseHeaders": {
        "Header-Name": "header and its value to test for all the requests"
      },
      "statusCode": 311, // status to validate for all the requests
    },
    "requests": [
      "request1", // use only default values
      {
        "target": "request2",
        "responseHeaders": {
          "Header-Name": "custom header and its value to test for this request"
        }
      }
    ]
  }
]

Contributing

Anyone is welcome to contribute, however, if you decide to get involved, please take a moment to review the guidelines:

Acknowledgements

Test Server Configs is only possible thanks to all the awesome contributors!

License

The code is available under the MIT license.