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.

Inputs

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

Example workflow

steps:
  - uses: actions/checkout@v
  - 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.

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.

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;

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.

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:

• Bug reports
• Feature requests
• Pull requests

Acknowledgements

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

License

The code is available under the MIT license.