d3ro-voice/apps/desktop/tests/main/services/KeyBindingService.test.ts

541 lines
19 KiB
TypeScript

import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { globalShortcut, ipcMain, powerMonitor } from 'electron'
import { uIOhook, UiohookKey } from 'uiohook-napi'
import type { UiohookKeyboardEvent, UiohookMouseEvent } from 'uiohook-napi'
import { IPC_CHANNELS } from '@d3ro/core/ipc-channels'
import {
MouseButton,
VK,
createDefaultBindingMap,
kb,
validateBinding,
} from '@d3ro/core/keybinding'
import type { KeyBinding, MouseButtonCode } from '@d3ro/core/types'
import {
configSet,
initInMemoryConfig,
resetInMemoryConfig,
saveKeyBindings,
} from '../../../src/main/services/ConfigService'
import {
getKeyBindingService,
uiohookCodeToVk,
type KeyBindingTriggerPayload,
} from '../../../src/main/services/KeyBindingService'
import { registerKeyBindingHandlers } from '../../../src/main/ipc/keybinding-handlers'
import { resetGlobalInputHookForTests } from '../../../src/main/services/global-input-hook'
type HookHandler<T> = (event: T) => void
function createHookHarness(): {
keydown: (event: Partial<UiohookKeyboardEvent> & { keycode: number }) => void
keyup: (event: Partial<UiohookKeyboardEvent> & { keycode: number }) => void
mousedown: (event: Partial<UiohookMouseEvent> & { button: unknown }) => void
mouseup: (event: Partial<UiohookMouseEvent> & { button: unknown }) => void
} {
const findListener = <T>(eventName: string): HookHandler<T> => {
const calls = vi.mocked(uIOhook.on).mock.calls
for (let i = calls.length - 1; i >= 0; i -= 1) {
const [registeredEvent, listener] = calls[i]
if (registeredEvent === eventName && typeof listener === 'function') {
return listener as unknown as HookHandler<T>
}
}
throw new Error(`No uIOhook listener registered for "${eventName}"`)
}
return {
keydown: (event) => {
findListener<UiohookKeyboardEvent>('keydown')({
type: 4,
time: Date.now(),
altKey: false,
ctrlKey: false,
metaKey: false,
shiftKey: false,
...event,
} as UiohookKeyboardEvent)
},
keyup: (event) => {
findListener<UiohookKeyboardEvent>('keyup')({
type: 5,
time: Date.now(),
altKey: false,
ctrlKey: false,
metaKey: false,
shiftKey: false,
...event,
} as UiohookKeyboardEvent)
},
mousedown: (event) => {
findListener<UiohookMouseEvent>('mousedown')({
type: 7,
time: Date.now(),
altKey: false,
ctrlKey: false,
metaKey: false,
shiftKey: false,
x: 0,
y: 0,
clicks: 1,
...event,
} as UiohookMouseEvent)
},
mouseup: (event) => {
findListener<UiohookMouseEvent>('mouseup')({
type: 8,
time: Date.now(),
altKey: false,
ctrlKey: false,
metaKey: false,
shiftKey: false,
x: 0,
y: 0,
clicks: 1,
...event,
} as UiohookMouseEvent)
},
}
}
function mb(
code: MouseButtonCode,
mods: Partial<Pick<KeyBinding, 'ctrl' | 'alt' | 'shift' | 'meta'>> = {},
): KeyBinding {
return {
device: 'mouse',
code,
ctrl: mods.ctrl ?? false,
alt: mods.alt ?? false,
shift: mods.shift ?? false,
meta: mods.meta ?? false,
}
}
const VK_F8 = VK.F1 + 7
const VK_F9 = VK.F1 + 8
describe('KeyBindingService', () => {
const hook = createHookHarness()
beforeEach(() => {
vi.clearAllMocks()
resetGlobalInputHookForTests()
initInMemoryConfig({
hotkeyEnabled: true,
suggestionEnabled: true,
})
const service = getKeyBindingService()
service.dispose()
})
afterEach(() => {
getKeyBindingService().dispose()
resetGlobalInputHookForTests()
resetInMemoryConfig()
})
describe('keyboard & mouse event handling and lifecycle', () => {
it('maps uiohook keycodes to canonical Windows VK codes and returns null for unknown codes', () => {
expect(uiohookCodeToVk(UiohookKey.F8)).toBe(VK_F8)
expect(uiohookCodeToVk(UiohookKey.AltRight)).toBe(VK.AltRight)
expect(uiohookCodeToVk(UiohookKey.A)).toBe(VK.A)
expect(uiohookCodeToVk(UiohookKey.Enter)).toBe(VK.Enter)
expect(uiohookCodeToVk(999_999)).toBeNull()
})
it('attaches uIOhook listeners on start, triggers keyboard actions, and cleans up on stop', () => {
const map = createDefaultBindingMap()
map.command = [kb(VK_F9, { ctrl: true })]
saveKeyBindings(map)
const service = getKeyBindingService()
const triggered: KeyBindingTriggerPayload[] = []
service.on('triggered', (payload) => triggered.push(payload))
service.loadFromConfig()
service.start()
expect(service.isRunning).toBe(true)
expect(service.registeredBindingCount).toBeGreaterThan(0)
hook.keydown({ keycode: UiohookKey.F9, ctrlKey: true })
hook.keyup({ keycode: UiohookKey.F9, ctrlKey: true })
expect(triggered).toEqual([
expect.objectContaining({
actionId: 'command',
type: 'pressed',
isDoublePress: false,
}),
expect.objectContaining({
actionId: 'command',
type: 'released',
isDoublePress: false,
}),
])
service.stop()
expect(service.isRunning).toBe(false)
expect(uIOhook.removeListener).toHaveBeenCalledWith('keydown', expect.any(Function))
expect(uIOhook.removeListener).toHaveBeenCalledWith('keyup', expect.any(Function))
expect(uIOhook.removeListener).toHaveBeenCalledWith('mousedown', expect.any(Function))
expect(uIOhook.removeListener).toHaveBeenCalledWith('mouseup', expect.any(Function))
})
it('skips keyboard bindings whose VK has no uiohook mapping (e.g., VK.Pause)', () => {
const map = createDefaultBindingMap()
for (const key of Object.keys(map) as Array<keyof typeof map>) {
map[key] = []
}
map.command = [kb(VK.Pause)]
saveKeyBindings(map)
const service = getKeyBindingService()
service.loadFromConfig()
expect(service.registeredBindingCount).toBe(0)
})
it('releases held bindings when powerMonitor emits lock-screen or suspend', () => {
const map = createDefaultBindingMap()
map.dictation = [kb(VK_F8)]
map['hands-free'] = []
saveKeyBindings(map)
const service = getKeyBindingService()
const triggered: KeyBindingTriggerPayload[] = []
service.on('triggered', (payload) => triggered.push(payload))
service.loadFromConfig()
service.start()
hook.keydown({ keycode: UiohookKey.F8 })
expect(triggered).toHaveLength(1)
expect(triggered[0]).toMatchObject({ actionId: 'dictation', type: 'pressed' })
const lockCall = vi
.mocked(powerMonitor.on)
.mock.calls.find(([event]) => (event as string) === 'lock-screen')
expect(lockCall).toBeDefined()
const lockHandler = lockCall?.[1] as (() => void) | undefined
lockHandler?.()
expect(triggered).toHaveLength(2)
expect(triggered[1]).toMatchObject({ actionId: 'dictation', type: 'released' })
})
})
describe('mouse button binding rules (MB1 rejection, MB2/MB3 modifier requirement, MB4/MB5 free binding)', () => {
it('rejects MB1 (Left click) both with and without modifiers in validation and IPC setBindings', async () => {
expect(validateBinding(mb(MouseButton.Left))).toEqual({
valid: false,
reason: 'device-disabled',
reasonKey: 'keybinding.disabled.mouseLeft',
warningKey: null,
})
expect(validateBinding(mb(MouseButton.Left, { ctrl: true, alt: true }))).toEqual({
valid: false,
reason: 'device-disabled',
reasonKey: 'keybinding.disabled.mouseLeft',
warningKey: null,
})
const handlers = new Map<string, (...args: unknown[]) => unknown>()
vi.mocked(ipcMain.handle).mockImplementation((channel, listener) => {
handlers.set(channel, listener as (...args: unknown[]) => unknown)
})
registerKeyBindingHandlers()
const setBindings = handlers.get(IPC_CHANNELS.KEYBINDING.SET_BINDINGS)!
const res = (await setBindings({}, {
actionId: 'dictation',
bindings: [mb(MouseButton.Left, { ctrl: true })],
})) as { success: boolean; error?: { details?: { reason?: string } } }
expect(res.success).toBe(false)
expect(res.error?.details?.reason).toBe('device-disabled')
})
it('requires a modifier for MB2 (Right) and MB3 (Middle), and triggers only when modifier is held', () => {
expect(validateBinding(mb(MouseButton.Right))).toMatchObject({
valid: false,
reason: 'modifier-required',
reasonKey: 'keybinding.reject.modifierRequired',
})
expect(validateBinding(mb(MouseButton.Middle))).toMatchObject({
valid: false,
reason: 'modifier-required',
reasonKey: 'keybinding.reject.modifierRequired',
})
expect(validateBinding(mb(MouseButton.Right, { ctrl: true }))).toMatchObject({
valid: true,
reason: null,
warningKey: 'keybinding.warning.mousePassthrough',
})
expect(validateBinding(mb(MouseButton.Middle, { alt: true }))).toMatchObject({
valid: true,
reason: null,
warningKey: 'keybinding.warning.mousePassthrough',
})
const map = createDefaultBindingMap()
map.command = [mb(MouseButton.Right, { ctrl: true })]
map.caption = [mb(MouseButton.Middle, { alt: true })]
saveKeyBindings(map)
const service = getKeyBindingService()
const triggered: KeyBindingTriggerPayload[] = []
service.on('triggered', (payload) => triggered.push(payload))
service.loadFromConfig()
service.start()
// Unmodified MB2 / MB3 must not trigger
hook.mousedown({ button: MouseButton.Right })
hook.mouseup({ button: MouseButton.Right })
hook.mousedown({ button: MouseButton.Middle })
hook.mouseup({ button: MouseButton.Middle })
expect(triggered).toHaveLength(0)
// Ctrl+MB2 and Alt+MB3 trigger their respective actions
hook.mousedown({ button: MouseButton.Right, ctrlKey: true })
hook.mouseup({ button: MouseButton.Right, ctrlKey: true })
hook.mousedown({ button: MouseButton.Middle, altKey: true })
hook.mouseup({ button: MouseButton.Middle, altKey: true })
expect(
triggered.filter((t) => t.type === 'pressed').map((t) => t.actionId),
).toEqual(['command', 'caption'])
})
it('allows free (unmodified) binding for MB4 (Back) and MB5 (Forward) and handles constituent mouseup release', () => {
expect(validateBinding(mb(MouseButton.Back))).toMatchObject({
valid: true,
reason: null,
warningKey: 'keybinding.warning.mousePassthrough',
})
expect(validateBinding(mb(MouseButton.Forward))).toMatchObject({
valid: true,
reason: null,
warningKey: 'keybinding.warning.mousePassthrough',
})
const map = createDefaultBindingMap()
map.dictation = [mb(MouseButton.Back)]
map['hands-free'] = []
map.command = [mb(MouseButton.Forward)]
saveKeyBindings(map)
const service = getKeyBindingService()
const triggered: KeyBindingTriggerPayload[] = []
service.on('triggered', (payload) => triggered.push(payload))
service.loadFromConfig()
service.start()
// Press MB4 unmodified -> hold starts; release MB4 while Alt is held -> constituent button still releases hold!
hook.mousedown({ button: MouseButton.Back })
hook.mouseup({ button: MouseButton.Back, altKey: true })
// Press MB5 unmodified -> triggers command
hook.mousedown({ button: MouseButton.Forward })
hook.mouseup({ button: MouseButton.Forward })
expect(triggered).toEqual([
expect.objectContaining({ actionId: 'dictation', type: 'pressed', isDoublePress: false }),
expect.objectContaining({ actionId: 'dictation', type: 'released', isDoublePress: false }),
expect.objectContaining({ actionId: 'command', type: 'pressed', isDoublePress: false }),
expect.objectContaining({ actionId: 'command', type: 'released', isDoublePress: false }),
])
})
})
describe('hold-to-talk vs double-press hands-free on shared binding', () => {
it('distinguishes single hold (dictation) from rapid double-press (hands-free) on the same key', () => {
const sharedBinding = kb(VK_F8)
const map = createDefaultBindingMap()
map.dictation = [sharedBinding]
map['hands-free'] = [sharedBinding]
saveKeyBindings(map)
const service = getKeyBindingService()
const triggered: KeyBindingTriggerPayload[] = []
service.on('triggered', (payload) => triggered.push(payload))
service.loadFromConfig()
service.start()
let now = 1_000
const nowSpy = vi.spyOn(Date, 'now').mockImplementation(() => now)
try {
// 1. Single press & hold (>400ms gap afterwards)
hook.keydown({ keycode: UiohookKey.F8, time: now })
now += 600
hook.keyup({ keycode: UiohookKey.F8, time: now })
expect(triggered).toEqual([
expect.objectContaining({ actionId: 'dictation', type: 'pressed', isDoublePress: false }),
expect.objectContaining({ actionId: 'dictation', type: 'released', isDoublePress: false }),
])
triggered.length = 0
// 2. Wait past double-press window, then double-press within 150ms
now += 1_000
hook.keydown({ keycode: UiohookKey.F8, time: now })
now += 80
hook.keyup({ keycode: UiohookKey.F8, time: now })
now += 100
hook.keydown({ keycode: UiohookKey.F8, time: now })
now += 80
hook.keyup({ keycode: UiohookKey.F8, time: now })
expect(triggered).toEqual([
expect.objectContaining({ actionId: 'dictation', type: 'pressed', isDoublePress: false }),
expect.objectContaining({ actionId: 'dictation', type: 'released', isDoublePress: false }),
expect.objectContaining({ actionId: 'hands-free', type: 'pressed', isDoublePress: true }),
expect.objectContaining({ actionId: 'hands-free', type: 'released', isDoublePress: true }),
])
} finally {
nowSpy.mockRestore()
}
})
})
describe('multiple bindings per action', () => {
it('triggers the same action from multiple distinct keyboard and mouse bindings independently', () => {
const map = createDefaultBindingMap()
map.dictation = [kb(VK_F8), mb(MouseButton.Back)]
map['hands-free'] = []
saveKeyBindings(map)
const service = getKeyBindingService()
const triggered: KeyBindingTriggerPayload[] = []
service.on('triggered', (payload) => triggered.push(payload))
service.loadFromConfig()
service.start()
hook.keydown({ keycode: UiohookKey.F8 })
hook.keyup({ keycode: UiohookKey.F8 })
hook.mousedown({ button: MouseButton.Back })
hook.mouseup({ button: MouseButton.Back })
expect(triggered).toEqual([
expect.objectContaining({
actionId: 'dictation',
type: 'pressed',
binding: expect.objectContaining({ device: 'keyboard', code: VK_F8 }),
}),
expect.objectContaining({
actionId: 'dictation',
type: 'released',
binding: expect.objectContaining({ device: 'keyboard', code: VK_F8 }),
}),
expect.objectContaining({
actionId: 'dictation',
type: 'pressed',
binding: expect.objectContaining({ device: 'mouse', code: MouseButton.Back }),
}),
expect.objectContaining({
actionId: 'dictation',
type: 'released',
binding: expect.objectContaining({ device: 'mouse', code: MouseButton.Back }),
}),
])
})
})
describe('suggestion capture accelerator registration & unregistration', () => {
it('registers suggestion accelerators only while suggestion capture is active and suggestionEnabled is true', () => {
const service = getKeyBindingService()
service.loadFromConfig()
service.start()
// On Windows/Linux, no globalShortcut is registered when suggestion overlay is inactive
vi.mocked(globalShortcut.register).mockClear()
vi.mocked(globalShortcut.unregister).mockClear()
service.setSuggestionCaptureActive(true)
const registeredWhenActive = vi
.mocked(globalShortcut.register)
.mock.calls.map(([accelerator]) => accelerator)
expect(registeredWhenActive).toEqual(
expect.arrayContaining([
'Control+Alt+Return',
'Control+Alt+Space',
'Control+Alt+Down',
'Control+Alt+Up',
'Control+Alt+Backspace',
]),
)
// Deactivating suggestion capture unregisters all captured accelerators
service.setSuggestionCaptureActive(false)
const unregisteredWhenInactive = vi
.mocked(globalShortcut.unregister)
.mock.calls.map(([accelerator]) => accelerator)
expect(unregisteredWhenInactive).toEqual(
expect.arrayContaining([
'Control+Alt+Return',
'Control+Alt+Space',
'Control+Alt+Down',
'Control+Alt+Up',
'Control+Alt+Backspace',
]),
)
})
it('releases captured accelerators when suggestionEnabled is turned off and re-registers when turned back on', () => {
const service = getKeyBindingService()
service.loadFromConfig()
service.start()
service.setSuggestionCaptureActive(true)
vi.mocked(globalShortcut.register).mockClear()
vi.mocked(globalShortcut.unregister).mockClear()
// Turning off suggestionEnabled releases captured shortcuts immediately
configSet('suggestionEnabled', false)
expect(vi.mocked(globalShortcut.unregister)).toHaveBeenCalledWith('Control+Alt+Return')
vi.mocked(globalShortcut.register).mockClear()
// Turning suggestionEnabled back on while capture is still wanted re-registers them
configSet('suggestionEnabled', true)
expect(vi.mocked(globalShortcut.register)).toHaveBeenCalledWith(
'Control+Alt+Return',
expect.any(Function),
)
})
it('triggers suggestion-accept for NumpadEnter and via OS capture fallback when uiohook misses the key', () => {
vi.useFakeTimers()
try {
const service = getKeyBindingService()
const triggered: KeyBindingTriggerPayload[] = []
service.on('triggered', (payload) => triggered.push(payload))
service.loadFromConfig()
service.start()
service.setSuggestionCaptureActive(true)
// 1) NumpadEnter via uiohook
hook.keydown({ keycode: UiohookKey.NumpadEnter, ctrlKey: true, altKey: true })
hook.keyup({ keycode: UiohookKey.NumpadEnter, ctrlKey: true, altKey: true })
expect(triggered.filter((t) => t.actionId === 'suggestion-accept' && t.type === 'pressed')).toHaveLength(1)
// 2) OS globalShortcut callback fires without a recent uiohook press (e.g. elevated window / UIPI)
vi.advanceTimersByTime(300)
const returnCall = vi
.mocked(globalShortcut.register)
.mock.calls.find(([accelerator]) => accelerator === 'Control+Alt+Return')
const callback = returnCall?.[1] as (() => void) | undefined
expect(callback).toBeDefined()
callback?.()
vi.advanceTimersByTime(30)
expect(triggered.filter((t) => t.actionId === 'suggestion-accept' && t.type === 'pressed')).toHaveLength(2)
} finally {
vi.useRealTimers()
}
})
})
})