Home

Awesome

Test Server Configs

CI

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

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:

<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:

<details> <summary>References</summary> </details>

ssl

Check correctness for the TLS/SSL configuration.

The requests should be served with:

<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.