Contributing a Patch to a Logstash Plugin

Test Driven Development, colloquially known as TDD, describes a methodology for using tests to guide evolution of source code. For our purposes, we are only going to use a part of it, that is, before writing the fix - we create tests that illustrate the bug by failing. We stop when we have written enough code to make the tests pass and submit the fix and tests as a patch. It is not necessary to write the tests before the fix, but it is very easy to write a passing test afterwards that may not actually verify that the fault is really fixed especially if the fault can be triggered via multiple execution paths or varying input data.

Logstash uses Rspec, a Ruby testing framework, to define and run the test suite. What follows is a summary of various sources.

Describe blocks (lines 5, 6 and 36 in Example 1).

describe(string){block} -> nil
describe(Class){block} -> nil

With RSpec, we are always describing the plugin method behavior. The describe block is added in logical sections and can accept either an existing class name or a string. The string used in line 5 is the plugin name. Line 6 is the register method, line 36 is the receive method. It is a RSpec convention to prefix instance methods with one hash and class methods with one dot.

Context blocks (lines 11, 19, 27 and 41).

context(string){block} -> nil

In RSpec, context blocks define sections that group tests by a variation. The string should start with the word when and then detail the variation. See line 11. The tests in the content block should should only be for that variation.

Let blocks (lines 7, 12, 20, 28, 37, 42 and 43).

let(symbol){block} -> nil

In RSpec, let blocks define resources for use in the test blocks. These resources are reinitialized for every test block. They are available as method calls inside the test block. Define let blocks in describe and context blocks, which scope the let block and any other nested blocks. You can use other let methods defined later within the let block body. See lines 7-9, which define the output resource and use the configuration method, defined with different variations in lines 12, 20 and 28.

Before blocks (line 50).

before(symbol){block} -> nil - symbol is one of :suite, :context, :example, but :all and :each are synonyms for :suite and :example respectively.

In RSpec, before blocks are used to further set up any resources that would have been initialized in a let block. You cannot define let blocks inside before blocks.

You can also define after blocks, which are typically used to clean up any setup activity performed by a before block.

It blocks (lines 14, 22, 30 and 54).

it(string){block} -> nil

In RSpec, it blocks set the expectations that verify the behavior of the tested code. The string should not start with it or should, but needs to express the outcome of the expectation. When put together the texts from the enclosing describe, context and it blocks should form a fairly readable sentence, as in lines 5, 6, 11 and 14:

outputs/riemann
#register when no protocol is specified the method completes without error

Readable code like this make the goals of tests easy to understand.

Expect method (lines 15, 23, 31, 55).

expect(object){block} -> nil

In RSpec, the expect method verifies a statement that compares an actual result to an expected result. The expect method is usually paired with a call to the to or not_to methods. Use the block form when expecting errors or observing for changes. The to or not_to methods require a matcher object that encapsulates the expected value. The argument form of the expect method encapsulates the actual value. When put together the whole line tests the actual against the expected value.

Matcher methods (lines 15, 23, 31, 55).

raise_error(error class|nil) -> matcher instance
be(object) -> matcher instance
eq(object) -> matcher instance
eql(object) -> matcher instance
  for more see http://www.relishapp.com/rspec/rspec-expectations/docs/built-in-matchers

In RSpec, a matcher is an object generated by the equivalent method call (be, eq) that will be used to evaluate the expected against the actual values.