feat: tests can opt-in to retries

Problem:
Tests have no way to retry without manually managing `before_each` and
`after_each` setup/teardown. This is painful. And busted does a good job
of guarding its internals and makes it impossible to extend it: AFAICT,
consumers have no way to access the current "test context", or the
current list of `before_each`/`after_each` hooks.

Solution:
Introduce `env.set_retries()`, which allows test authors to optionally retry a test:

```lua
it('...', function()
  set_retries(2) -- If the test fails, it will be retried up to 2 times.
end)
```

Testing:

    luarocks --local remove busted --force && luarocks --local make && ~/.luarocks/bin/busted --pattern=core

Author: justinmk

busted/init.lua

@@ -1,5 +1,5 @@
 local function init(busted)
-  local block = require 'busted.block'(busted)
+  local block = require 'busted.block' (busted)
 
   local file = function(file)
     busted.wrap(file.run)
@@ -20,6 +20,8 @@ local function init(busted)
   local it = function(element)
     local parent = busted.context.parent(element)
     local finally
+    local attempt = 1
+    local max_attempts = 1
 
     if not block.lazySetup(parent) then
       -- skip test if any setup failed
@@ -31,24 +33,40 @@ local function init(busted)
     block.rejectAll(element)
     element.env.finally = function(fn) finally = fn end
     element.env.pending = busted.pending
+    element.env.set_retries = function(n) max_attempts = n + 1 end
 
+    local status = busted.status('success')
     local pass, ancestor = block.execAll('before_each', parent, true)
+    if pass and busted.safe_publish('test', { 'test', 'start' }, element, parent) then
+      while attempt <= max_attempts do
+        -- Run after_each from previous attempt before before_each (for retries)
+        if attempt > 1 then
+          block.dexecAll('after_each', ancestor, true)
+          pass, ancestor = block.execAll('before_each', parent, true)
+        end
+        local attempt_status = busted.safe('it', element.run, element)
 
-    if pass then
-      local status = busted.status('success')
-      if busted.safe_publish('test', { 'test', 'start' }, element, parent) then
-        status:update(busted.safe('it', element.run, element))
         if finally then
           block.reject('pending', element)
           status:update(busted.safe('finally', finally, element))
         end
-      else
-        status = busted.status('error')
+
+        if attempt_status:success() then
+          status = busted.status('success')
+          break
+        else
+          status = attempt_status
+        end
+
+        attempt = attempt + 1
       end
-      busted.safe_publish('test', { 'test', 'end' }, element, parent, tostring(status))
-    end
 
-    block.dexecAll('after_each', ancestor, true)
+      -- Run after_each after the last try.
+      block.dexecAll('after_each', ancestor, true)
+    else
+      status = busted.status('error')
+    end
+    busted.safe_publish('test', { 'test', 'end' }, element, parent, tostring(status))
   end
 
   local pending = function(element)
@@ -93,7 +111,7 @@ local function init(busted)
   local stub   = busted.require 'luassert.stub'
   local match  = busted.require 'luassert.match'
 
-  require 'busted.fixtures'  -- just load into the environment, not exposing it
+  require 'busted.fixtures' -- just load into the environment, not exposing it
 
   busted.export('assert', assert)
   busted.export('spy', spy)

busted/outputHandlers/base.lua

@@ -70,7 +70,8 @@ return function()
       name = handler.getFullName(element),
       message = message,
       randomseed = parent and parent.randomseed,
-      isError = isError
+      isError = isError,
+      id = tostring(element)
     }
     formatted.element.trace = element.trace or debug
 
@@ -120,6 +121,12 @@ return function()
     local insertTable
 
     if status == 'success' then
+      -- Remove any failures for this test since it succeeded
+      for i = #handler.failures, 1, -1 do
+        if handler.failures[i].id == tostring(element) then
+          table.remove(handler.failures, i)
+        end
+      end
       insertTable = handler.successes
       handler.successesCount = handler.successesCount + 1
     elseif status == 'pending' then

spec/core_spec.lua

@@ -13,6 +13,29 @@ assert(type(mock) == 'table')
 assert(type(match) == 'table')
 assert(type(assert) == 'table')
 
+describe('retry test', function()
+  local attempt_count = 0
+
+  before_each(function()
+    attempt_count = attempt_count + 1
+    print("Before each for attempt " .. attempt_count)
+  end)
+
+  after_each(function()
+    print("After each for attempt " .. attempt_count)
+  end)
+
+  it('should succeed on second attempt', function()
+    set_retries(2)  -- 3 total attempts
+    print("Running attempt " .. attempt_count)
+    if attempt_count < 3 then
+      assert.is_true(false, 'Failing attempt ' .. attempt_count)
+    else
+      assert.is_true(true, 'Succeeding on attempt ' .. attempt_count)
+    end
+  end)
+end)
+
 describe('Before each', function()
   local test_val = false