Skip to content

Latest commit

 

History

History
273 lines (199 loc) · 8.58 KB

README.md

File metadata and controls

273 lines (199 loc) · 8.58 KB
Raw

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

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

References

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

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;
References

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

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.