assert logic inverter

# @note Instead of commenting out a test or using skip_test(), use this!
#
# Tells an assert that it's 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).
#
# == Usage
# 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).
#
# @example Typical usage
#   expect_failure('expected to fail due to PE-1234') do
#     assert_equal(400, response.code, 'bad response code from API call')
#   end
#
# @example 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>.'
#
# @example 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'>
#
# @param [String] explanation A description of why this assert is expected to
#                             fail
# @yieldreturn [void] block is expected to either raise a
#                     <tt>MiniTest:Assertion</tt> or else return a value that
#                     will be ignored
# @raise [RuntimeError] if the code block passed to this method does not raise
#                       a <tt>MiniTest::Assertion</tt> (i.e., if the assert
#                       passes)
# @return [void] return value is expected to be ignored
# @author Chris Cowell-Shah (<tt>ccs@puppetlabs.com</tt>)
def expect_failure(explanation)
  begin
    yield  # code block should contain an assert that you expect to fail
  rescue MiniTest::Assertion => failed_assertion
    # Yay! The assert in the code block failed, as expected.
    # Swallow the failure so the test passes.
    logger.warn '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: '#{msg}'")
end