MGTK: Add automation interface

Add a mechanism for test automation to interact directly with MGTK,
allowing queries like "how many windows are open?", "what is the name
of the top-most window?", and "where is the top-most window's title
bar?" Since the MGTK API is relatively stable this is a safe
integration point.

Several tests updated to take advantage of this, but more can be
done.

Author: inexorabletash

src/mgtk/MGTK.md

@@ -1349,3 +1349,26 @@ _DA specific:_
 _DA specific:_
 
 * Following a window move, resize or close, call `JUMP_TABLE_CLEAR_UPDATES` to allow DeskTop to handle update events. This will not redraw the DA window, however.
+
+# Automation
+
+MGTK exposes an automation interface, intended for use by automated tests. It works as follows:
+
+* Wait for the keyboard strobe to be cleared. (`KBD` high bit off)
+* Depress both Open Apple (`BUTN0`) and Solid Apple (`BUTN1`)
+* Submit a keypress of ASCII `NUL` (Ctrl+Shift+2 on the Apple II keyboard)
+* Wait for the keyboard strobe to be cleared.
+* Release both Open Apple (`BUTN0`) and Solid Apple (`BUTN1`)
+* Save copies of any bytes that will be modified by the following.
+* Store any "in" call parameters into memory. (`$0003` is a good location)
+* Set memory address `$0000` to the MGTK call number, and `$0001`/`$0002` to the address of parameter data.
+* Submit any keypress.
+* Wait for the keyboard strobe to be cleared.
+* Read the call result from address `$00`.
+* Load any "out" call parameters from memory.
+* Submit any keypress.
+* Wait for the keyboard strobe to be cleared.
+
+Note that addresses assume the banking that this MGTK instance is running with. DeskTop normally runs with the Aux ZP active and MGTK-visible resoures like window titles in Aux or Aux LC memory. The Selector module has an MGTK instance in main memory and runs with the Main ZP active except for the alert code which resizes in the Aux LC bank.
+
+Automation can use this interface to query for open windows and inspect their properties.

src/mgtk/mgtk.inc

@@ -692,6 +692,7 @@ event_modifier_solid_apple = 1 << 1
 
 ;;; Used in FindControl
 .enum Part
+        inactive        = 0
         up_arrow        = 1
         left_arrow      = 1
         down_arrow      = 2

src/mgtk/mgtk.s

@@ -5463,6 +5463,10 @@ irq_entry:
         sta     input::key
         bit     KBDSTRB         ; clear strobe
 
+        ;; Check if automation hook
+        jsr     CheckAutomationHook
+        bcc     end
+
         ;; Check if "MouseKeys" mode should be activated
         jsr     CheckActivateMouseKeys
         bcc     end
@@ -9884,6 +9888,37 @@ scale_y:
 .endproc ; GetKey
 
 
+.proc CheckAutomationHook
+        ;; Check for OA+SA+Ctrl+Shift+2
+        lda     input::modifiers
+        cmp     #3
+        bne     ignore
+        lda     input::key
+        cmp     #0              ; Ctrl-@
+        bne     ignore
+
+        jsr     wait_for_key
+
+        COPY_BYTES 3, $00, params
+
+        jsr     SaveParamsAndStack ; restored by call below
+        jsr     MGTKEntry
+params: .res    3
+        sta     $00
+        jsr     RestoreParamsAndStack
+
+        FALL_THROUGH_TO wait_for_key
+wait_for_key:
+:       lda     KBD
+        bpl     :-
+        sta     KBDSTRB
+        RETURN C=0
+
+ignore:
+        RETURN C=1
+.endproc ; CheckAutomationHook
+
+
 ;;; Assert: `kbd_mouse_state` is not `kKeyboardMouseStateInactive`
 .proc HandleKeyboardMouse
         cmp     #kKeyboardMouseStateMouseKeys

tests/apple_menu.lua

@@ -58,7 +58,7 @@ test.Step(
     test.Snap("verify alert shown")
     drive:load(current)
     a2d.DialogOK()
-    test.Snap("verify Calculator opened")
+    test.ExpectEquals(a2dtest.GetFrontWindowTitle(), "Calc", "Calculator should be open")
     a2d.CloseWindow()
 end)
 
@@ -72,6 +72,6 @@ test.Step(
     test.Snap("verify alert shown")
     drive:load(current)
     a2d.DialogOK()
-    test.Snap("verify CONTROL.PANELS window opemed")
+    test.ExpectEqualsIgnoreCase(a2dtest.GetFrontWindowTitle(), "CONTROL.PANELS", "Control Panels window should be open")
     a2d.CloseWindow()
 end)

tests/calculator.lua

@@ -5,9 +5,6 @@
 
   ============================================================]]--
 
-local INITIAL_HEADER_X = 280
-local INITIAL_HEADER_Y = 55
-
 test.Step(
   "Cursor doesn't home",
   function()
@@ -20,8 +17,10 @@ test.Step(
   "Move window and mouse cursor",
   function()
     a2d.OpenPath("/A2.DESKTOP/APPLE.MENU/CALCULATOR")
+    local x,y = a2dtest.GetFrontWindowDragCoords()
+
     a2d.InMouseKeysMode(function(m)
-        m.MoveToApproximately(INITIAL_HEADER_X,INITIAL_HEADER_Y)
+        m.MoveToApproximately(x,y)
         m.ButtonDown()
         m.MoveToApproximately(400,100)
         m.ButtonUp()
@@ -35,8 +34,10 @@ test.Step(
   "Window and volume icons",
   function()
     a2d.OpenPath("/A2.DESKTOP/APPLE.MENU/CALCULATOR")
+    local x,y = a2dtest.GetFrontWindowDragCoords()
+
     a2d.InMouseKeysMode(function(m)
-        m.MoveToApproximately(INITIAL_HEADER_X,INITIAL_HEADER_Y)
+        m.MoveToApproximately(x,y)
         m.ButtonDown()
         m.MoveToApproximately(500,20)
         m.ButtonUp()
@@ -58,8 +59,10 @@ test.Step(
   "Obscured window",
   function()
     a2d.OpenPath("/A2.DESKTOP/APPLE.MENU/CALCULATOR")
+    local x,y = a2dtest.GetFrontWindowDragCoords()
+
     a2d.InMouseKeysMode(function(m)
-        m.MoveToApproximately(INITIAL_HEADER_X,INITIAL_HEADER_Y)
+        m.MoveToApproximately(x,y)
         m.ButtonDown()
         m.MoveToApproximately(280,191)
         m.ButtonUp()

tests/close_all.lua

@@ -8,19 +8,17 @@
 test.Step(
   "Close all using modifier-click",
   function()
-    a2dtest.ExpectNothingHappened(function()
-        a2d.ClearSelection()
-        a2d.OpenPath("/A2.DESKTOP/EXTRAS", true) -- leave parent open
-        a2d.InMouseKeysMode(function(m)
-            m.MoveToApproximately(40, 26)
-            apple2.PressOA()
-            m.Click()
-            apple2.ReleaseOA()
-            a2d.WaitForRepaint()
-            m.MoveToApproximately(0,0)
-        end)
-        a2d.ClearSelection()
+    a2d.ClearSelection()
+    a2d.OpenPath("/A2.DESKTOP/EXTRAS", true) -- leave parent open
+    local x,y = a2dtest.GetFrontWindowCloseBoxCoords()
+    a2d.InMouseKeysMode(function(m)
+        m.MoveToApproximately(x,y)
+        apple2.PressOA()
+        m.Click()
+        apple2.ReleaseOA()
     end)
+    a2d.WaitForRepaint()
+    test.ExpectEquals(a2dtest.GetWindowCount(), 0, "all windows should be closed")
 end)
 
 test.Variants(
@@ -30,16 +28,14 @@ test.Variants(
   },
   function(idx)
     a2d.ClearSelection()
-    a2dtest.ExpectNothingHappened(function()
-        a2d.OpenPath("/A2.DESKTOP/EXTRAS", true) -- leave parent open
-        if idx == 1 then
-          a2d.OASAShortcut("W")
-        else
-          a2d.OASAShortcut("w")
-        end
-        a2d.WaitForRepaint()
-        a2d.ClearSelection()
-    end)
+    a2d.OpenPath("/A2.DESKTOP/EXTRAS", true) -- leave parent open
+    if idx == 1 then
+      a2d.OASAShortcut("W")
+    else
+      a2d.OASAShortcut("w")
+    end
+    a2d.WaitForRepaint()
+    test.ExpectEquals(a2dtest.GetWindowCount(), 0, "all windows should be closed")
 end)
 
 --[[
@@ -64,7 +60,7 @@ test.Variants(
     else
       apple2.ReleaseOA()
     end
-    test.Snap("verify all windows closed")
+    test.ExpectEquals(a2dtest.GetWindowCount(), 0, "all windows should be closed")
 end)
 ]]--
 
@@ -85,6 +81,6 @@ end)
       a2d.OASAShortcut("w")
     end
     a2d.WaitForRepaint()
-    test.Snap("verify all windows closed")
+    test.ExpectEquals(a2dtest.GetWindowCount(), 0, "all windows should be closed")
 end)
 ]]--

tests/close_window.lua

@@ -16,12 +16,14 @@ test.Step(
   function()
     a2d.OpenPath("/A2.DESKTOP")
     a2d.SelectAndOpen("EXTRAS")
+    local count = a2dtest.GetWindowCount()
+    local x,y = a2dtest.GetFrontWindowCloseBoxCoords()
     a2d.InMouseKeysMode(function(m)
-        m.MoveToApproximately(40, 26)
+        m.MoveToApproximately(x,y)
         m.Click()
     end)
     a2d.WaitForRepaint()
-    test.Snap("verify only one window closed")
+    test.ExpectEquals(a2dtest.GetWindowCount(), count - 1, "one window should have closed")
     a2d.CloseAllWindows()
 end)
 
@@ -35,6 +37,7 @@ test.Variants(
   function(idx)
     a2d.OpenPath("/A2.DESKTOP")
     a2d.SelectAndOpen("EXTRAS")
+    local count = a2dtest.GetWindowCount()
     a2d.OpenMenu(a2d.FILE_MENU)
     if idx == 1 then
       a2d.OAShortcut("W")

tests/date_and_time.lua

@@ -23,18 +23,16 @@ test.Step(
   "Escape and Return",
   function()
     a2d.SelectPath("/A2.DESKTOP/APPLE.MENU/CONTROL.PANELS/DATE.AND.TIME")
-
-    a2dtest.ExpectNothingHappened(function()
-        a2d.OpenSelection()
-        apple2.ReturnKey()
-        a2d.WaitForRepaint()
-    end)
-
-    a2dtest.ExpectNothingHappened(function()
-        a2d.OpenSelection()
-        apple2.EscapeKey()
-        a2d.WaitForRepaint()
-    end)
+    local count = a2dtest.GetWindowCount()
+    a2d.OpenSelection()
+    apple2.ReturnKey()
+    a2d.WaitForRepaint()
+    test.ExpectEquals(a2dtest.GetWindowCount(), count, "expect window closed")
+
+    a2d.OpenSelection()
+    apple2.EscapeKey()
+    a2d.WaitForRepaint()
+    test.ExpectEquals(a2dtest.GetWindowCount(), count, "expect window closed")
 
     a2d.CloseAllWindows()
 end)

tests/desk_accessories.lua

@@ -8,7 +8,7 @@ test.Step(
     a2d.CloseWindow()
 end)
 
-function MoveDoesntRepaintTest(name, path, x, y, opt_threshold)
+function MoveDoesntRepaintTest(name, path, opt_threshold)
   test.Step(
     name .. " doesn't repaint on non-move",
     function()
@@ -25,6 +25,9 @@ function MoveDoesntRepaintTest(name, path, x, y, opt_threshold)
 
       a2d.SelectPath(path)
       a2d.OpenSelection()
+
+      local x,y = a2dtest.GetFrontWindowDragCoords()
+
       a2d.InMouseKeysMode(function(m)
           m.MoveToApproximately(x,y)
           emu.wait(2/60)
@@ -45,21 +48,21 @@ function MoveDoesntRepaintTest(name, path, x, y, opt_threshold)
   end)
 end
 
-MoveDoesntRepaintTest("Calculator", "/A2.DESKTOP/APPLE.MENU/CALCULATOR", 280, 55)
-MoveDoesntRepaintTest("Calendar", "/A2.DESKTOP/APPLE.MENU/CALENDAR", 280, 40)
-MoveDoesntRepaintTest("Key Caps", "/A2.DESKTOP/APPLE.MENU/KEY.CAPS", 280, 50)
-MoveDoesntRepaintTest("Control Panel", "/A2.DESKTOP/APPLE.MENU/CONTROL.PANELS/CONTROL.PANEL", 280, 30)
-MoveDoesntRepaintTest("Joystick", "/A2.DESKTOP/APPLE.MENU/CONTROL.PANELS/JOYSTICK", 280, 50, 0.02)
-MoveDoesntRepaintTest("Map", "/A2.DESKTOP/APPLE.MENU/CONTROL.PANELS/MAP", 280, 40)
-MoveDoesntRepaintTest("Options", "/A2.DESKTOP/APPLE.MENU/CONTROL.PANELS/OPTIONS", 280, 45)
-MoveDoesntRepaintTest("Views", "/A2.DESKTOP/APPLE.MENU/CONTROL.PANELS/VIEWS", 280, 50)
-MoveDoesntRepaintTest("Bounce", "/A2.DESKTOP/APPLE.MENU/TOYS/BOUNCE", 280, 45, 0.05)
-MoveDoesntRepaintTest("Eyes", "/A2.DESKTOP/APPLE.MENU/TOYS/EYES", 280, 60)
-MoveDoesntRepaintTest("Lights Out", "/A2.DESKTOP/APPLE.MENU/TOYS/LIGHTS.OUT", 280, 60)
-MoveDoesntRepaintTest("Neko", "/A2.DESKTOP/APPLE.MENU/TOYS/NEKO", 280, 50)
-MoveDoesntRepaintTest("Puzzle", "/A2.DESKTOP/APPLE.MENU/TOYS/PUZZLE", 280, 70)
-MoveDoesntRepaintTest("CD Remote", "/A2.DESKTOP/EXTRAS/CD.REMOTE", 280, 70)
-MoveDoesntRepaintTest("Scientific Calculator", "/A2.DESKTOP/EXTRAS/SCI.CALC", 280, 50)
+MoveDoesntRepaintTest("Calculator", "/A2.DESKTOP/APPLE.MENU/CALCULATOR")
+MoveDoesntRepaintTest("Calendar", "/A2.DESKTOP/APPLE.MENU/CALENDAR")
+MoveDoesntRepaintTest("Key Caps", "/A2.DESKTOP/APPLE.MENU/KEY.CAPS")
+MoveDoesntRepaintTest("Control Panel", "/A2.DESKTOP/APPLE.MENU/CONTROL.PANELS/CONTROL.PANEL")
+MoveDoesntRepaintTest("Joystick", "/A2.DESKTOP/APPLE.MENU/CONTROL.PANELS/JOYSTICK", 0.02)
+MoveDoesntRepaintTest("Map", "/A2.DESKTOP/APPLE.MENU/CONTROL.PANELS/MAP")
+MoveDoesntRepaintTest("Options", "/A2.DESKTOP/APPLE.MENU/CONTROL.PANELS/OPTIONS")
+MoveDoesntRepaintTest("Views", "/A2.DESKTOP/APPLE.MENU/CONTROL.PANELS/VIEWS")
+MoveDoesntRepaintTest("Bounce", "/A2.DESKTOP/APPLE.MENU/TOYS/BOUNCE", 0.05)
+MoveDoesntRepaintTest("Eyes", "/A2.DESKTOP/APPLE.MENU/TOYS/EYES")
+MoveDoesntRepaintTest("Lights Out", "/A2.DESKTOP/APPLE.MENU/TOYS/LIGHTS.OUT")
+MoveDoesntRepaintTest("Neko", "/A2.DESKTOP/APPLE.MENU/TOYS/NEKO")
+MoveDoesntRepaintTest("Puzzle", "/A2.DESKTOP/APPLE.MENU/TOYS/PUZZLE")
+MoveDoesntRepaintTest("CD Remote", "/A2.DESKTOP/EXTRAS/CD.REMOTE")
+MoveDoesntRepaintTest("Scientific Calculator", "/A2.DESKTOP/EXTRAS/SCI.CALC")
 
 -- ============================================================