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

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

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.

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

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

• 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)

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

Check if all common files are served correctly.

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

Check if cache-busting is working.

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

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.

Check if errors are served as desired.

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

Check if gzip is enable even if mangled headers.

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.

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.

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;

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.

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

[
  {
    "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"
        }
      }
    ]
  }
]

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

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

The code is available under the MIT license.