tests(helpers): add helper functionality for testing

spec/00-helpers_spec.lua

@@ -0,0 +1,201 @@
+describe("Spec helpers", function()
+
+  local helpers
+
+  setup(function()
+    helpers = require("spec.helpers")
+  end)
+
+
+
+  describe("(un)loading", function()
+
+    it("removes terminal and system from package.loaded", function()
+      helpers.load()
+      assert.is_not_nil(package.loaded["terminal"])
+      helpers.unload()
+      assert.is_nil(package.loaded["terminal"])
+      assert.is_nil(package.loaded["system"])
+    end)
+
+
+    it("reloads terminal after unload", function()
+      helpers.unload()
+      local _ = helpers.load()
+      assert.is_not_nil(package.loaded["terminal"])
+      helpers.unload()
+      assert.is_nil(package.loaded["terminal"])
+      local t2 = helpers.load()
+      assert.is_table(t2)
+      assert.is_not_nil(package.loaded["terminal"])
+    end)
+
+
+    it("returns terminal module with expected API", function()
+      helpers.unload()
+      local terminal = helpers.load()
+      assert.is_table(terminal.input)
+    end)
+
+
+    it("returns a fresh terminal table on reload", function()
+      helpers.unload()
+      local t1 = helpers.load()
+      helpers.unload()
+      local t2 = helpers.load()
+      assert.is_table(t2)
+      assert.is_table(t2.utils)
+      assert.is_table(t2.input)
+      assert.not_equal(t1, t2)
+    end)
+
+  end)
+
+
+
+  describe("termsize", function()
+
+    it("defaults to 25x80", function()
+      helpers.load()
+
+      local rows, cols = helpers.get_termsize()
+      assert.equals(25, rows)
+      assert.equals(80, cols)
+    end)
+
+
+    it("patches system.termsize to use mocked values", function()
+      helpers.load()
+
+      helpers.set_termsize(30, 90)
+
+      local system = require("system")
+      local rows, cols = system.termsize()
+      assert.equals(30, rows)
+      assert.equals(90, cols)
+    end)
+
+  end)
+
+
+
+  describe("keyboard input mock", function()
+
+    it("returns bytes from the helper _readkey buffer", function()
+      helpers.load()
+
+      helpers._push_input("ab")
+
+      local b1 = helpers._readkey()
+      local b2 = helpers._readkey()
+      local b3 = helpers._readkey()
+
+      assert.equals(string.byte("a"), b1)
+      assert.equals(string.byte("b"), b2)
+      assert.is_nil(b3)
+    end)
+
+
+    it("returns nil and error when pushing an error entry", function()
+      helpers.load()
+
+      helpers._push_input(nil, "some-error")
+
+      local b, err = helpers._readkey()
+      assert.is_nil(b)
+      assert.equals("some-error", err)
+    end)
+
+
+    it("patches system._readkey to use the mock buffer", function()
+      helpers.load()
+
+      helpers._push_input("X")
+
+      local system = require("system")
+      local b = system._readkey()
+
+      assert.equals(string.byte("X"), b)
+    end)
+
+
+    it("terminal.input.readansi() returns data read from the mock buffer", function()
+      local terminal = helpers.load()
+
+      helpers._push_input("X")
+
+      local rawkey, keytype = terminal.input.readansi(0.01)
+      assert.equals("X", rawkey)
+      assert.equals("char", keytype)
+    end)
+
+  end)
+
+
+
+  describe("output capture", function()
+
+    it("accumulates writes between reads", function()
+      local terminal = helpers.load()
+
+      terminal.output.write("one")
+      local first = helpers.get_output()
+
+      terminal.output.write("two")
+      local second = helpers.get_output()
+
+      assert.equals("one", first)
+      assert.equals("onetwo", second)
+    end)
+
+
+    it("clears output and starts fresh", function()
+      local terminal = helpers.load()
+
+      terminal.output.write("abc")
+      assert.equals("abc", helpers.get_output())
+
+      helpers.clear_output()
+      terminal.output.write("xyz")
+
+      local out = helpers.get_output()
+      assert.equals("xyz", out)
+    end)
+
+  end)
+
+
+
+  describe("keys lookup", function()
+
+    it("is read-only", function()
+      helpers.load()
+
+      assert.has_error(function()
+        helpers.keys.enter = "something"
+      end, "table is read-only")
+    end)
+
+
+    it("returns a raw sequence that maps back to the same keyname", function()
+      local terminal = helpers.load()
+
+      local raw = helpers.keys.enter
+      local keyname_from_map = terminal.input.keymap.default_key_map[raw]
+      local keyname_from_keys = terminal.input.keymap.default_keys.enter
+
+      assert.equals(keyname_from_keys, keyname_from_map)
+    end)
+
+
+    it("errors on unknown key name", function()
+      helpers.load()
+
+      assert.has_error(function()
+        local _ = helpers.keys.this_key_does_not_exist
+      end, "Unknown key-name: this_key_does_not_exist")
+    end)
+
+  end)
+
+end)

spec/05-scroll_stack_spec.lua

@@ -1,33 +1,19 @@
-describe("Scroll stack", function()
+local helpers = require "spec.helpers"
 
-  local stack, scroll, old_sys_termsize
 
-  before_each(function()
-    _G._TEST = true
+describe("Scroll stack", function()
 
-    local sys = require "system"
-    old_sys_termsize = sys.termsize
-    if os.getenv("GITHUB_ACTIONS") then
-      sys.termsize = function()
-        return 25, 80
-      end
-    end
+  local terminal, stack, scroll
 
-    stack = require "terminal.scroll.stack"
-    scroll = require "terminal.scroll"
+  before_each(function()
+    terminal = helpers.load()
+    stack = terminal.scroll.stack
+    scroll = terminal.scroll
   end)
 
 
   after_each(function()
-    _G._TEST = nil
-
-    require("system").termsize = old_sys_termsize
-
-    for mod in pairs(package.loaded) do
-      if mod:match("^terminal") then
-        package.loaded[mod] = nil
-      end
-    end
+    helpers.unload()
   end)
 
 

spec/06-cursor_spec.lua

@@ -1,33 +1,22 @@
-describe("Cursor", function()
+local helpers = require "spec.helpers"
 
-  local cursor, old_sys_termsize
 
-  before_each(function()
-    for mod in pairs(package.loaded) do
-      if mod:match("^terminal") then
-        package.loaded[mod] = nil
-      end
-    end
+describe("Cursor", function()
 
-    local sys = require "system"
-    old_sys_termsize = sys.termsize
-    if os.getenv("GITHUB_ACTIONS") then
-      sys.termsize = function()
-        return 25, 80
-      end
-    end
+  local terminal, cursor
 
-    cursor = require "terminal.cursor"
+  before_each(function()
+    terminal = helpers.load()
+    cursor = terminal.cursor
   end)
 
 
   after_each(function()
-    require("system").termsize = old_sys_termsize
+    helpers.unload()
   end)
 
 
 
-
   describe("visible.set()", function()
 
     it("returns ANSI sequence for hiding the cursor", function()

spec/11-screen_spec.lua

@@ -1,7 +1,5 @@
-#!/usr/bin/env lua
+local helpers = require "spec.helpers"
 
---- Tests for terminal.ui.screen module
--- @module spec.11-screen_spec
 
 describe("terminal.ui.screen", function()
 
@@ -10,15 +8,14 @@ describe("terminal.ui.screen", function()
   local terminal
 
   before_each(function()
+    terminal = helpers.load()
     Screen = require("terminal.ui.panel.screen")
     Panel = require("terminal.ui.panel")
-    terminal = require("terminal")
   end)
 
+
   after_each(function()
-    Screen = nil
-    Panel = nil
-    terminal = nil
+    helpers.unload()
   end)
 
 

spec/13-bar_spec.lua

@@ -1,12 +1,15 @@
+local helpers = require "spec.helpers"
+
+
 describe("terminal.ui.panel.bar", function()
 
   local Bar
   local terminal
 
   setup(function()
     -- Load modules
+    terminal = helpers.load()
     Bar = require("terminal.ui.panel.bar")
-    terminal = require("terminal")
 
     -- Mock terminal functions for testing
     terminal.cursor = {
@@ -29,6 +32,7 @@ describe("terminal.ui.panel.bar", function()
     -- Unset modules for clean test isolation
     Bar = nil
     terminal = nil -- luacheck: ignore
+    helpers.unload()
   end)
 
 

spec/14-text_panel_spec.lua

@@ -1,12 +1,15 @@
+local helpers = require "spec.helpers"
+
+
 describe("terminal.ui.panel.text", function()
 
   local TextPanel
   local terminal
   local text
 
   setup(function()
+    terminal = helpers.load()
     TextPanel = require("terminal.ui.panel.text")
-    terminal = require("terminal")
     text = require("terminal.text")
 
     -- Mock terminal functions
@@ -39,6 +42,7 @@ describe("terminal.ui.panel.text", function()
     TextPanel = nil
     terminal = nil -- luacheck: ignore
     text = nil
+    helpers.unload()
   end)
 
 

spec/15-key_bar_spec.lua

@@ -1,3 +1,6 @@
+local helpers = require "spec.helpers"
+
+
 describe("terminal.ui.panel.key_bar", function()
 
   local KeyBar
@@ -6,8 +9,8 @@ describe("terminal.ui.panel.key_bar", function()
 
   setup(function()
     -- Load modules
+    terminal = helpers.load()
     KeyBar = require("terminal.ui.panel.key_bar")
-    terminal = require("terminal")
     text = require("terminal.text")
 
     -- Mock terminal functions for testing
@@ -30,6 +33,7 @@ describe("terminal.ui.panel.key_bar", function()
     -- Unset modules for clean test isolation
     KeyBar = nil
     terminal = nil -- luacheck: ignore
+    helpers.unload()
   end)