gemba 0.1.1 → 0.2.0

data/test/shared/tk_test_helper.rb

@@ -49,6 +49,52 @@ module TeekTestHelper
   # Default timeout for subprocess tests (can be overridden via TK_TEST_TIMEOUT env var)
   DEFAULT_SUBPROCESS_TIMEOUT = 5
 
+  # Tcl bgerror capture preamble — prepended to subprocess code so that
+  # any unhandled Tcl background error is written to a log file instead
+  # of vanishing into the void. tk_subprocess reads the log after the
+  # subprocess exits and appends it to stderr.
+  BGERROR_PREAMBLE = <<~'RUBY'
+    require 'teek'
+    module BgerrorCapture
+      def initialize(*)
+        super
+        if (path = ENV['GEMBA_BGERROR_LOG'])
+          tcl_eval(%Q{
+            proc bgerror {msg} {
+              set fd [open {#{path}} a]
+              puts $fd "bgerror: $msg"
+              if {[info exists ::errorInfo]} {
+                puts $fd $::errorInfo
+              }
+              puts $fd "---"
+              close $fd
+            }
+          })
+        end
+      end
+
+      # Wrap after() to capture the full Ruby backtrace before Teek converts
+      # the exception to a Tcl error (at which point the backtrace is lost).
+      def after(ms, on_error: :raise, &block)
+        path = ENV['GEMBA_BGERROR_LOG']
+        return super unless path
+        super(ms, on_error: on_error) do
+          begin
+            block.call
+          rescue => e
+            File.open(path, 'a') do |f|
+              f.puts "Ruby exception in after(#{ms}ms): #{e.class}: #{e.message}"
+              f.puts e.backtrace.join("\n")
+              f.puts "---"
+            end
+            raise
+          end
+        end
+      end
+    end
+    Teek::App.prepend(BgerrorCapture)
+  RUBY
+
   def tk_subprocess(code, coverage: true, timeout: nil)
     timeout ||= Integer(ENV['TK_TEST_TIMEOUT'] || DEFAULT_SUBPROCESS_TIMEOUT)
 
@@ -57,18 +103,31 @@ module TeekTestHelper
     load_paths = $LOAD_PATH.select { |p| p.start_with?(project_root) }
     load_path_args = load_paths.flat_map { |p| ["-I", p] }
 
-    # Prepend SimpleCov setup for coverage merging
-    full_code = coverage ? "#{TeekTestHelper.simplecov_preamble}\n#{code}" : code
+    # Temp file for capturing Tcl bgerror output
+    require 'tempfile'
+    bgerror_file = Tempfile.new(['bgerror', '.log'])
+    bgerror_path = bgerror_file.path
+    bgerror_file.close
+
+    # Prepend SimpleCov + bgerror capture
+    preamble = coverage ? "#{TeekTestHelper.simplecov_preamble}\n" : ""
+    full_code = "#{preamble}#{BGERROR_PREAMBLE}\n#{code}"
+
+    # Write code to temp file so backtraces show real line numbers
+    code_file = Tempfile.new(['tk_test', '.rb'])
+    code_file.write(full_code)
+    code_file.close
 
     # Pass env vars to subprocess
     env = {}
     env['VISUAL'] = '1' if ENV['VISUAL']
     env['COVERAGE'] = '1' if ENV['COVERAGE']
+    env['GEMBA_BGERROR_LOG'] = bgerror_path
 
     # -rbundler/setup activates Bundler in the subprocess so path: gems
     # (e.g. teek, teek-sdl2 from sibling repos) are on the load path.
     stdin, stdout, stderr, wait_thr = Open3.popen3(
-      env, RbConfig.ruby, "-rbundler/setup", *load_path_args, "-e", full_code
+      env, RbConfig.ruby, "-rbundler/setup", *load_path_args, code_file.path
     )
     stdin.close
 
@@ -84,6 +143,10 @@ module TeekTestHelper
       end
     end
 
+    # Read bgerror log before cleanup
+    bgerrors = File.read(bgerror_path).strip rescue ""
+    File.delete(bgerror_path) rescue nil
+
     unless status
       # Timed out - capture any output before killing so errors are visible
       out = stdout.read_nonblock(64 * 1024) rescue ""
@@ -92,7 +155,10 @@ module TeekTestHelper
       wait_thr.join
       stdout.close
       stderr.close
-      return [false, out, "Test timed out after #{timeout}s\n#{err}", nil]
+      err = "Test timed out after #{timeout}s\n#{err}"
+      err = "#{err}\nTcl bgerror log:\n#{bgerrors}" unless bgerrors.empty?
+      code_file.unlink rescue nil
+      return [false, out, err, nil]
     end
 
     out = stdout.read
@@ -100,6 +166,10 @@ module TeekTestHelper
     stdout.close
     stderr.close
 
+    # Append bgerrors to stderr so they surface in test output
+    err = "#{err}\nTcl bgerror log:\n#{bgerrors}" unless bgerrors.empty?
+    code_file.unlink rescue nil
+
     [status.success?, out, err, status]
   end
 
@@ -283,6 +353,23 @@ module TeekTestHelper
   # The test code has access to `app` (a Teek::App instance) and minitest assertions.
   # Do NOT create your own TkRoot or call root.destroy - worker manages this.
   #
+  # == event generate gotcha: mouse button events ==
+  #
+  # The TestWorker calls `app.hide` (wm withdraw .) after every test.
+  # `event generate <Button-N>` silently does nothing when the root window is
+  # withdrawn because widgets are not mapped/viewable without a visible ancestor.
+  # Always call `app.show` + `app.update` before generating mouse button events:
+  #
+  #   picker.show
+  #   app.show    # ← required: deiconify root so widgets are viewable
+  #   app.update  # ← let Tk map all windows
+  #   app.tcl_eval("event generate .widget <Button-3> -x 10 -y 10")
+  #   app.update
+  #
+  # Key events additionally require focus:
+  #   app.tcl_eval("focus -force .widget")
+  #   app.update
+  #
   # Example:
   #   def test_something
   #     assert_tk_app("should work") do

data/test/support/achievements_window_helpers.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Minimal config stand-in for AchievementsWindow tests.
+# The window only reads ra_unofficial? from config at build time.
+FakeConfig = Struct.new(:ra_unofficial) {
+  def ra_unofficial? = ra_unofficial
+} unless defined?(FakeConfig)
+
+# Build a plain rom hash suitable for RomLibrary stubbing.
+def make_rom_entry(id:, title:, platform: 'gba', game_code: 'AGB-TEST', md5: "#{id}abcd")
+  { 'rom_id' => id, 'title' => title, 'platform' => platform,
+    'game_code' => game_code, 'path' => "/games/#{id}.gba", 'md5' => md5 }
+end unless respond_to?(:make_rom_entry, true)
+
+# Wrap an array of rom hashes in a minimal RomLibrary-compatible struct.
+def make_rom_library(*roms)
+  Struct.new(:roms) { def all = roms }.new(roms)
+end unless respond_to?(:make_rom_library, true)

data/test/support/fake_core.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Minimal Core stub — no mGBA dependency, just a programmable memory map.
+# Used by achievement backend tests to simulate bus reads without a real ROM.
+class FakeCore
+  def initialize
+    @mem = Hash.new(0)
+  end
+
+  # Write a byte into the fake memory map.
+  # @param address [Integer] GBA address
+  # @param value   [Integer] 0..255
+  def poke(address, value)
+    @mem[address] = value & 0xFF
+  end
+
+  # Reads back what was poked (or 0 for anything not explicitly written).
+  def bus_read8(address)
+    @mem[address]
+  end
+
+  def destroyed?
+    false
+  end
+end

data/test/support/fake_ra_runtime.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# Test double for Gemba::RARuntime (the C extension).
+#
+# Mirrors the full RARuntime interface so RetroAchievements::Backend can be
+# tested without a real rcheevos instance or ROM memory.
+#
+# Usage:
+#   rt = FakeRARuntime.new
+#   rt.queue_triggers("101", "102")   # do_frame will return these once
+#   rt.rp_message = "Playing Stage 1" # get_richpresence returns this
+#   rt.rp_activate_result = false     # activate_richpresence returns false
+class FakeRARuntime
+  attr_reader   :activated, :deactivated, :cleared, :reset_count
+  attr_reader   :rp_script
+  attr_accessor :rp_message, :rp_activate_result
+
+  def initialize
+    @activated          = {}   # id => memaddr
+    @deactivated        = []
+    @trigger_queue      = []   # Array<Array<String>> — one entry consumed per do_frame
+    @cleared            = false
+    @reset_count        = 0
+    @rp_script          = nil
+    @rp_message         = nil
+    @rp_activate_result = true
+  end
+
+  # Queue one frame's worth of triggered achievement IDs.
+  # Each call adds one "frame": the next do_frame call pops and returns it.
+  def queue_triggers(*ids)
+    @trigger_queue << ids.flatten.map(&:to_s)
+  end
+
+  # -- RARuntime interface ----------------------------------------------------
+
+  def activate(id, memaddr)
+    @activated[id.to_s] = memaddr.to_s
+  end
+
+  def deactivate(id)
+    @deactivated << id.to_s
+    @activated.delete(id.to_s)
+  end
+
+  def reset_all
+    @reset_count += 1
+  end
+
+  def clear
+    @activated.clear
+    @deactivated.clear
+    @trigger_queue.clear
+    @cleared = true
+  end
+
+  # Returns the next queued batch of triggered IDs, or [] if nothing queued.
+  def do_frame(_core)
+    @trigger_queue.shift || []
+  end
+
+  def count
+    @activated.size
+  end
+
+  def activate_richpresence(script)
+    @rp_script = script
+    @rp_activate_result
+  end
+
+  def get_richpresence(_core)
+    @rp_message
+  end
+end

data/test/support/fake_requester.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# Synchronous test double for the RetroAchievements HTTP transport.
+#
+# Designed to match Teek::BackgroundWork's fluent interface so it can be
+# injected without any branching in ra_request — the same code path runs
+# in production and tests.
+#
+# Usage:
+#   req = FakeRequester.new
+#   req.stub(r: "login2", body: { "Success" => true, "Token" => "tok" })
+#   req.stub(r: "gameid", body: { "GameID" => 42 })
+#
+#   backend = Backend.new(app: nil, runtime: FakeRARuntime.new, requester: req)
+#   backend.login_with_token(username: "u", token: "t")
+#   assert backend.authenticated?
+#   assert req.requested?("login2")
+class FakeRequester
+  # Returned by call() — mirrors BackgroundWork's fluent on_progress/on_done chain.
+  # on_progress fires synchronously with the canned result so callers behave
+  # identically to the async production path without needing an event loop.
+  class Result
+    def initialize(value)
+      @value = value
+    end
+
+    def on_progress(&block)
+      block.call(@value)
+      self
+    end
+
+    def on_done(&block)
+      self
+    end
+  end
+
+  attr_reader :requests
+
+  def initialize
+    @stubs    = {}   # r_string => [json_or_nil, ok_bool]
+    @requests = []   # all params hashes, in call order
+  end
+
+  # Register a canned response for a given r= value.
+  def stub(r:, body: nil, ok: true)
+    @stubs[r.to_s] = [body, ok]
+  end
+
+  # Called by ra_request with the same signature as Teek::BackgroundWork.new.
+  # Ignores the block (which contains real Net::HTTP code) and returns a
+  # Result that fires on_progress synchronously with the canned response.
+  def call(_app, params, mode: nil, **_opts, &_block)
+    @requests << params.dup
+    r      = (params[:r] || params["r"]).to_s
+    result = @stubs.fetch(r, [nil, false])
+    Result.new(result)
+  end
+
+  # True if at least one request with the given r= value was made.
+  def requested?(r)
+    @requests.any? { |p| (p[:r] || p["r"]).to_s == r.to_s }
+  end
+
+  # All params hashes for requests with the given r= value.
+  def requests_for(r)
+    @requests.select { |p| (p[:r] || p["r"]).to_s == r.to_s }
+  end
+end

data/test/support/player_helpers.rb

@@ -36,7 +36,7 @@ end
 # Falls back to xdotool to force focus if polling alone doesn't work.
 def poll_until_focused(player, timeout_ms: 2_000, &block)
   app = player.app
-  renderer = player.viewport.renderer
+  renderer = player.frame.viewport.renderer
   deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout_ms / 1000.0
   tried_xdotool = false
   check = proc do
@@ -60,14 +60,21 @@ def poll_until_focused(player, timeout_ms: 2_000, &block)
   app.after(50, &check)
 end
 
-def poll_until_ready(player, timeout_ms: 5_000, &block)
-  app = player.app
+# Polls every 50ms until the given condition block returns truthy, then
+# yields the action block.  Aborts with exit 1 if the deadline is exceeded.
+#
+# Example — wait for a menu entry to become enabled:
+#   poll_until(app, timeout_ms: 3_000,
+#              condition: -> { app.tcl_eval('...entrycget 0 -state').strip == 'normal' }) do
+#     app.command(...)
+#   end
+def poll_until(app, timeout_ms: 5_000, condition:, label: "condition", &block)
   deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout_ms / 1000.0
   check = proc do
-    if player.ready?
+    if condition.call
       block.call
     elsif Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
-      $stderr.puts "FAIL: Player not ready within #{timeout_ms}ms"
+      $stderr.puts "FAIL: #{label} not true within #{timeout_ms}ms"
       exit 1
     else
       app.after(50, &check)
@@ -75,3 +82,11 @@ def poll_until_ready(player, timeout_ms: 5_000, &block)
   end
   app.after(50, &check)
 end
+
+def poll_until_ready(player, timeout_ms: 5_000, &block)
+  poll_until(player.app, timeout_ms: timeout_ms,
+             condition: -> { player.ready? },
+             label: "Player not ready") do
+    block.call
+  end
+end

data/test/test_achievement.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require "gemba/headless"
+require "gemba/achievements"
+
+class TestAchievement < Minitest::Test
+  def test_unearned_by_default
+    ach = Gemba::Achievements::Achievement.new(
+      id: 'x', title: 'T', description: 'D', points: 10, earned_at: nil
+    )
+    refute ach.earned?
+    assert_nil ach.earned_at
+  end
+
+  def test_earn_returns_copy_with_timestamp
+    ach = Gemba::Achievements::Achievement.new(
+      id: 'x', title: 'T', description: 'D', points: 10, earned_at: nil
+    )
+    earned = ach.earn
+    assert earned.earned?
+    assert_instance_of Time, earned.earned_at
+  end
+
+  def test_earn_does_not_mutate_original
+    ach = Gemba::Achievements::Achievement.new(
+      id: 'x', title: 'T', description: 'D', points: 10, earned_at: nil
+    )
+    ach.earn
+    refute ach.earned?
+  end
+end