SmokeTest v0.2.0 SmokeTest View Source

A configurable Plug middleware to quickly find errors that might prevent a deployment. It can also be used as an application health-check.

Usage

SmokeTest can be easily configured for Plug or Phoenix servers. The only options you need to provide is the OTP application that contains your smoketest configuration.

Plug

For pure Plug applications, simply use Plug.Router.forward/2 on the path you’d like to use for smoke-testing.

defmodule ExamplePlugWeb.Router do
  use Plug.Router

  forward "/ping", to: SmokeTest, init_opts: [otp_app: :example]
end

Phoenix

For Phoenix applications, adding SmokeTest to your router is also a one-liner. You can pass Smoketest into Phoenix.Router.forward/4, choosing whatever route you prefer for smoke testing.

defmodule ExamplePhoenixWeb.Router do
  use ExampleWeb, :router

  forward "/ping", SmokeTest, [otp_app: :example]

end

Configuration

Configuration can be provided as part of your application config, or as a keyword list in the plug itself. Options from your application config will be overriden by explicit plug configuration.

Configuration values are expected to resolved at compile time.

Registering Tests

Tests should be provided as a map with the following properties:

  • id the id of the test.
  • test either a three item tuple of { Module, :fun, [args]} or an anonymous function.
  • timeout (optional) the amount of time (in ms) the test has to complete. Defaults to 1000.

Each test should return a two-item tuple of {:ok, term} or {:error, reason}. Items that don’t fulfill this spec are marked as a failure.

tests: [
  # Test "db" calls a Module.function(args), with a timeout of 5000 ms
  %{ id: "db", test: {Module, :function, [args]}, timeout: 5000} ,

  # Test "cluster" calls an anonymous function, with a timeout of 1500ms
  %{ id: "cluster", test: fn -> :net_adm.names() end, timeout: 1500 },

  # Test "other" calls another  module, and uses the default timeout of 1000
  %{ id: "other", test: {Other.Module, :function, [args]} },
]

Inlined into your configuration:

# application configuration
config :example, SmokeTest,
  tests: [
    %{ id: "db", test: {Module, :function, [args]}, timeout: 5000} ,
    %{ id: "cluster", test: fn -> :net_adm.names() end, timeout: 1500 },
    %{ id: "other", test: {Other.Module, :function, [args]} },
  ]

# plug configuration
forward "/ping", SmokeTest, [
  otp_app: :example,
  tests: [
    %{ id: "db", test: {Module, :function, [args]}, timeout: 5000} ,
    %{ id: "cluster", test: fn -> :net_adm.names() end, timeout: 1500 },
    %{ id: "other", test: {Other.Module, :function, [args]} },
  ]
]

Additional Configuration options

Response Status

The status to return on success and failure is also configurable. Success defaults to 200, and failure defaults to 503

# application configuration
config :example, Smoketest,
  success_status: 201,
  failure_status: 500

# plug configuration
forward "/ping", SmokeTest, [
  otp_app: :example,
  success_status: 201,
  failure_status: 500
]

Json Encoder

A json encoder is required to diplay output. A Poison adapter is provided by default, and need not be configured if present in your deps. See SmokeTest.Adapters.JSONEncoder.Poison for more information.

To explicitly configure your own adapter, add the following to your SmokeTest configuration:

# application config
config :example, SmokeTest,
  json_encoder: SmokeTest.Adapters.JSONEncoder.Poison

# plug config
forward "/ping", SmokeTest, [
  otp_app: :example,
  json_encoder: SmokeTest.Adapters.JSONEncoder.Poison
]

Example JSON Output

Here’s a quick example output of a failed smoketest.

{
  "app":"example",
  "status":"failures",
  "version":"0.0.1",
  "timeouts":[
    {
      "id": "cluster"
      "result": "No response",
      "timeout": 15000
    }
  ],
  "failures":[
      {
        "id":"DB"
        "timeout":5000,
        "result":"Argument Error"
      }
  ],
}

And a successful one

{
  "app":"example",
  "status":"ok",
  "version":"0.0.1",
}

Encoders

The Poison JSON encoder is included with this module. If present, the module will automatically include the adapter for you. See SmokeTest.Adapters.JSONEncoder and SmokeTest.Adapters.JSONEncoder.Poison for more details.

Link to this section Summary

Functions

Callback implementation for Plug.call/2

Callback implementation for Plug.init/1

Link to this section Functions

Callback implementation for Plug.call/2.

Callback implementation for Plug.init/1.