Add unit testing for the stack structure

Use Busted as the unit testing framework

.busted

@@ -0,0 +1,39 @@
+-- SPDX-License-Identifier: Unlicense
+
+-- This is free and unencumbered software released into the public domain.
+--
+-- Anyone is free to copy, modify, publish, use, compile, sell, or distribute
+-- this software, either in source code form or as a compiled binary, for any
+-- purpose, commercial or non-commercial, and by any means.
+--
+-- In jurisdictions that recognize copyright laws, the author or authors of
+-- this software dedicate any and all copyright interest in the software to
+-- the public domain.  We make this dedication for the benefit of the public
+-- at large and to the detriment of our heirs and successors.  We intend this
+-- dedication to be an overt act of relinquishment in perpetuity of all
+-- present and future rights to this software under copyright law.
+--
+-- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+-- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+-- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+-- THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+-- AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+-- CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+--
+-- For more information, please refer to <https://unlicense.org/>
+
+
+return {
+	_all = {
+		coverage = false,
+		lua = './test/nvim-shim'
+	},
+	default = {
+		verbose = true,
+	},
+	unit = {
+		ROOT = {'./test/unit/'},
+	}
+}
+
+-- vim:ft=lua

.gitignore

@@ -1,2 +1,6 @@
 # Tag file created by Vim
 doc/tags
+test/xdg/config/nvim/
+test/xdg/local/share/nvim/
+test/xdg/local/state/nvim/
+!test/xdg/local/share/nvim/site/pack/testing/start/rainbow-delimiters

HACKING.rst

@@ -5,6 +5,26 @@
 #################################
 
 
+Testing
+#######
+
+Unit testing
+============
+
+We use busted_ for unit testing.  A unit is a self-contained module which can
+be used on its own independent of the editor.  Execute `make check` to run unit
+tests.  The `busted` binary must be available on the system `$PATH`.
+
+End to end testing
+==================
+
+We use Vader_ for testing the entire plugin.  Execute `:Vader test/vader/**/*`
+to run all Vader tests.  As of the time of writing this there is a bug in
+Vader: tests contain Lua code, which will set the file type of the Vader result
+buffer to `lua`. This is annoying, but it does not affect the test results.
+
+
+
 Design decisions
 ################
 
@@ -58,15 +78,6 @@ are arguments which returns the strategy table.
    }
 
 
-Testing
-#######
-
-We use Vader_ for testing.  Execute `:Vader test/vader/**/*` to run all Vader
-tests.  As of the time of writing this there is a bug in Vader: tests contain
-Lua code, which will set the file type of the Vader result buffer to `lua`.
-This is annoying, but it does not affect the test results.
-
-
 Strategies
 ##########
 
@@ -286,4 +297,5 @@ changes with a range that spans the entire tree for that language.
 
 
 
+.. _busted: https://lunarmodules.github.io/busted/#defining-tests
 .. _Vader: https://github.com/junegunn/vader.vim

makefile

@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: Unlicense
+
+# This is free and unencumbered software released into the public domain.
+#
+# Anyone is free to copy, modify, publish, use, compile, sell, or distribute
+# this software, either in source code form or as a compiled binary, for any
+# purpose, commercial or non-commercial, and by any means.
+#
+# In jurisdictions that recognize copyright laws, the author or authors of
+# this software dedicate any and all copyright interest in the software to
+# the public domain.  We make this dedication for the benefit of the public
+# at large and to the detriment of our heirs and successors.  We intend this
+# dedication to be an overt act of relinquishment in perpetuity of all
+# present and future rights to this software under copyright law.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+# THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+# AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+# For more information, please refer to <https://unlicense.org/>
+
+
+.PHONY: check unit-test
+
+check: unit-test
+
+unit-test:
+	eval $$(luarocks path --lua-version 5.1 --bin) && busted --run unit

test/nvim-shim

@@ -0,0 +1,37 @@
+#!/bin/sh
+# SPDX-License-Identifier: Unlicense
+
+# This is free and unencumbered software released into the public domain.
+#
+# Anyone is free to copy, modify, publish, use, compile, sell, or distribute
+# this software, either in source code form or as a compiled binary, for any
+# purpose, commercial or non-commercial, and by any means.
+#
+# In jurisdictions that recognize copyright laws, the author or authors of
+# this software dedicate any and all copyright interest in the software to
+# the public domain.  We make this dedication for the benefit of the public
+# at large and to the detriment of our heirs and successors.  We intend this
+# dedication to be an overt act of relinquishment in perpetuity of all
+# present and future rights to this software under copyright law.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+# THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+# AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+# For more information, please refer to <https://unlicense.org/>
+
+
+# A shim which acts as a command-line interface adapter to use Neovim as a Lua
+# interpreter.
+
+# Set custom XDG base directory paths to isolate the test Neovim from the
+# user's own configuration and data files.
+export XDG_CONFIG_HOME='test/xdg/config/'
+export XDG_STATE_HOME='test/xdg/local/state/'
+export XDG_DATA_HOME='test/xdg/local/share/'
+
+# We have to explicitly enable plugins, see ':h -l'
+nvim --cmd 'set loadplugins' -l $@

test/unit/stack_spec.lua

@@ -0,0 +1,85 @@
+local Stack = require 'rainbow-delimiters.stack'
+
+describe('The stack data structure #stack', function()
+	describe('The empty stack', function()
+		local stack
+
+		before_each(function() stack = Stack.new() end)
+
+		it('Can instantiate an empty stack', function()
+			assert.is_not._nil(stack)
+		end)
+
+		it('Is empty', function()
+			assert.is.equal(0, stack:size())
+		end)
+
+		it('Can push items onto the stack', function ()
+			stack:push('a')
+			stack:push('b')
+			assert.is.equal(2, stack:size())
+		end)
+	end)
+
+	describe('Stack with contents', function()
+		local stack, items
+
+		before_each(function()
+			items = {'a', 'b', 'c', 'd'}
+			stack = Stack.new(items)
+		end)
+
+		it('Can instantiate stack with contents', function()
+			assert.is_not._nil(stack)
+		end)
+
+		it('Holds the correct amount of items', function()
+			assert.is.equal(4, stack:size())
+		end)
+
+		it('Can inspect the topmost element', function ()
+			local top = stack:peek()
+			assert.is.equal('d', top)
+		end)
+
+		it('Can pop items off the stack in reverse order', function()
+			for i = 3, 0, -1 do
+				local val = stack:pop()
+				assert.is.equal(items[i + 1], val)
+				assert.is.equal(i, stack:size())
+			end
+		end)
+
+		it('Can push an item onto the stack', function()
+			local val = 'e'
+			stack:push(val)
+			assert.is.equal(5, stack:size())
+			assert.is.equal(val, stack:pop())
+		end)
+	end)
+
+	describe('Stack traversal', function()
+		it('Traverses the stack from top to bottom', function()
+			local counter = 1
+			local expected_indices = {4, 3, 2, 1}
+			local expected_values  = {'d', 'c', 'b', 'a'}
+
+			local stack = Stack.new {'a', 'b', 'c', 'd'}
+			for i, v in stack:iter() do
+				local index = expected_indices[counter]
+				local value = expected_values[ counter]
+				assert.is.equal(index, i)
+				assert.is.equal(value, v)
+				counter = counter + 1
+			end
+		end)
+
+		it('Does nothing for an empty stack', function()
+			local stack = Stack.new()
+			for _i, _v in stack:iter() do
+				-- This must never run because the stack is empty
+				assert.is_true(false)
+			end
+		end)
+	end)
+end)

test/xdg/README.rst

@@ -0,0 +1,6 @@
+.. default-role:: code
+
+
+This directory exists so that we can point Neovim to its sub-directories
+instead of the default XDG base directories.  This isolates the Neovim instance
+used during testing from the user's own configuration and data.

test/xdg/local/share/nvim/site/pack/testing/start/rainbow-delimiters

@@ -0,0 +1 @@
+../../../../../../../../../