Module: Beaker::DSL::Structure

Included in:
Beaker::DSL
Defined in:
lib/beaker/dsl/structure.rb

Overview

These are simple structural elements necessary for writing understandable tests and ensuring cleanup actions happen. If using a third party test runner they are unnecessary.

To include this in your own test runner a method #logger should be available to yield a logger that implements Logger‘s interface. As well as a method #teardown_procs that yields an array.

Examples:

Structuring a test case.

test_name 'Look at me testing things!' do
  teardown do
    ...clean up actions...
  end

  step 'Prepare the things' do
    ...setup steps...
  end

  step 'Test the things' do
    ...tests...
  end

  step 'Expect this to fail' do
    expect_failure('expected to fail due to PE-1234') do
    assert_equal(400, response.code, 'bad response code from API call')
  end
end

Instance Method Summary collapse

Instance Method Details

#expect_failure(explanation, &block) ⇒ Object

Wrap an assert that is supposed to fail due to a product bug, an undelivered feature, or some similar situation.

This converts failing asserts into passing asserts (so we can continue to run the test even though there are underlying product bugs), and converts passing asserts into failing asserts (so we know when the underlying product bug has been fixed).

Pass an assert as a code block, and pass an explanatory message as a parameter. The assert’s logic will be inverted (so passes turn into fails and fails turn into passes).

Examples:

Typical usage

expect_failure('expected to fail due to PE-1234') do
  assert_equal(400, response.code, 'bad response code from API call')
end

Output when a product bug would normally cause the assert to fail

Warning: An assertion was expected to fail, and did.
This is probably due to a known product bug, and is probably not a problem.
Additional info: 'expected to fail due to PE-6995'
Failed assertion: 'bad response code from API call.
<400> expected but was <409>.'

Output when the product bug has been fixed

<RuntimeError: An assertion was expected to fail, but passed.
This is probably because a product bug was fixed, and "expect_failure()"
needs to be removed from this assert.
Additional info: 'expected to fail due to PE-6996'>

Parameters:

  • explanation (String) —

    A description of why this assert is expected to fail

  • block (Proc) —

    block of code is expected to either raise an Assertions or else return a value that will be ignored

Raises:

  • (RuntimeError) —

    if the code block passed to this method does not raise a Assertions (i.e., if the assert passes)

Author:



109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
 
# File 'lib/beaker/dsl/structure.rb', line 109

def expect_failure(explanation, &block)
  begin
    yield if block_given?  # code block should contain an assert that you expect to fail
  rescue Beaker::DSL::Assertions, Minitest::Assertion => failed_assertion
    # Yay! The assert in the code block failed, as expected.
    # Swallow the failure so the test passes.
    logger.notify 'An assertion was expected to fail, and did. ' +
                    'This is probably due to a known product bug, ' +
                    'and is probably not a problem. ' +
                    "Additional info: '#{explanation}' " +
                    "Failed assertion: '#{failed_assertion}'"
    return
  end
  # Uh-oh! The assert in the code block unexpectedly passed.
  fail('An assertion was expected to fail, but passed. ' +
           'This is probably because a product bug was fixed, and ' +
           '"expect_failure()" needs to be removed from this test. ' +
           "Additional info: '#{explanation}'")
end

#step(step_name, &block) ⇒ Object

Provides a method to help structure tests into coherent steps.

Parameters:

  • step_name (String) —

    The name of the step to be logged.

  • block (Proc) —

    The actions to be performed in this step.



39
40
41
42
 
# File 'lib/beaker/dsl/structure.rb', line 39

def step step_name, &block
  logger.notify "\n  * #{step_name}\n"
  yield if block_given?
end

#teardown(&block) ⇒ Object

Declare a teardown process that will be called after a test case is complete.

Examples:

Always remove /etc/puppet/modules

teardown do
  on(master, puppet_resource('file', '/etc/puppet/modules',
    'ensure=absent', 'purge=true'))
end

Parameters:

  • block (Proc) —

    block of code to execute during teardown



65
66
67
 
# File 'lib/beaker/dsl/structure.rb', line 65

def teardown &block
  @teardown_procs << block
end

#test_name(my_name, &block) ⇒ Object

Provides a method to name tests.

Parameters:

  • my_name (String) —

    The name of the test to be logged.

  • block (Proc) —

    The actions to be performed during this test.



50
51
52
53
 
# File 'lib/beaker/dsl/structure.rb', line 50

def test_name my_name, &block
  logger.notify "\n#{my_name}\n"
  yield if block_given?
end