flan/advanced-camera-card
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

test: Add browser based tests for keyboard focus handling (#2647)

Browse Source
This commit is contained in:
Dermot Duffy
2026-08-02 16:38:17 -07:00
committed by GitHub
parent 17146c8ca6
commit 5d247d4074
7 changed files with 669 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tests/card-controller/card-element-manager.browser.test.ts
+115
View File
@@ -0,0 +1,115 @@
import { describe, expect, it, onTestFinished } from 'vitest';
import { createLogAction } from '../../src/utils/action';
import { MountedCard } from '../browser/mounted-card';
import {
CARD_INITIALIZED_MESSAGE,
createInitializedAutomation,
createStillCameraHASS,
createStillImageCardConfig,
deepQueryAll,
getFocusedElement,
pressKey,
pressTab,
} from '../browser/test-utils';
// What the automation writes when it runs, written as the pattern the console
// is later searched for.
const KEY_MESSAGE = /key pressed/;
const mountCard = async (): Promise<MountedCard> => {
const card = await MountedCard.create(
createStillImageCardConfig({
automations: [
createInitializedAutomation(),
{
triggers: [{ trigger: 'key', key: 'z' }],
actions: [createLogAction(KEY_MESSAGE.source)],
},
],
}),
createStillCameraHASS(),
);
await card.events.waitForFirst('advanced-camera-card:media:loaded');
return card;
};
/**
* Tab until focus is past the card, however many places within it can take
* focus. The bound is a runaway guard rather than a count, so that a card
* which never lets focus go fails instead of tabbing forever; it is taken from
* the card's own size, since nothing in it can be a tab stop twice.
*/
const tabPastCard = async (card: MountedCard): Promise<void> => {
const bound = deepQueryAll(card.card, '*').length;
// Tabbing starts from the top of the page, so the first press is the one
// that reaches the card.
await pressTab();
for (
let press = 0;
press < bound && card.card.contains(document.activeElement);
press++
) {
await pressTab();
}
};
/**
* Something to tab on to after the card, standing in for whatever else is on
* the dashboard below it.
*/
const addTrailingControl = (): HTMLElement => {
const control = document.createElement('button');
document.body.append(control);
onTestFinished(() => control.remove());
return control;
};
describe('CardElementManager', () => {
it('should be reachable by tabbing', async () => {
const card = await mountCard();
// No pointer is used here at all. A card that can only be reached by
// clicking on it is out of reach of a keyboard-only user.
await pressTab();
expect(getFocusedElement()).toBe(card.card);
await pressKey('z');
await card.console.waitForMessage(KEY_MESSAGE);
});
it('should be possible to tab beyond the card', async () => {
const card = await mountCard();
const trailingControl = addTrailingControl();
await tabPastCard(card);
// Tabbing continues past the card and out the other side. A card that kept
// focus would strand a user part way down the dashboard.
expect(getFocusedElement()).toBe(trailingControl);
});
it('should be reachable by tabbing after being put back in the document', async () => {
const card = await mountCard();
// Home Assistant takes a card out of the document when the dashboard tab it
// is on is left, and puts the same element back on return.
card.detach();
card.attach();
await card.console.waitForMessage(CARD_INITIALIZED_MESSAGE, { count: 2 });
await pressTab();
expect(getFocusedElement()).toBe(card.card);
await pressKey('z');
await card.console.waitForMessage(KEY_MESSAGE);
});
});
tests/card-controller/initialization/session-manager.browser.test.ts
+13 -28
View File
@@ -3,31 +3,21 @@ import { describe, expect, it, vi } from 'vitest';
import type { RawAdvancedCameraCardConfig } from '../../../src/config/types';
import { MountedCard } from '../../browser/mounted-card';
import {
CARD_INITIALIZED_MESSAGE,
createInitializedAutomation,
createStillCameraHASS,
createStillImageCameraConfig,
createStillImageCardConfig,
isMediaLoadedInfoEventDetail,
} from '../../browser/test-utils';
const STARTED_MESSAGE = 'card-started';
const OTHER_CAMERA_ENTITY = 'camera.other';
const createConfig = (
overrides?: Partial<RawAdvancedCameraCardConfig>,
): RawAdvancedCameraCardConfig =>
createStillImageCardConfig({
automations: [
{
triggers: [{ trigger: 'initialized' }],
actions: [
{
action: 'fire-dom-event',
advanced_camera_card_action: 'log',
message: STARTED_MESSAGE,
},
],
},
],
automations: [createInitializedAutomation()],
...overrides,
});
@@ -39,11 +29,6 @@ const mount = async (
createStillCameraHASS({ cameras: [OTHER_CAMERA_ENTITY] }),
);
// Only the messages the automation logged, since the card logs other things at
// the same level.
const getStartedMessages = (card: MountedCard): string[] =>
card.console.getMessages('info').filter((message) => message === STARTED_MESSAGE);
// The cameras the card has actually loaded media for, in order. Media that
// named no camera is left out, since these are only read to ask which camera
// the card ended up on.
@@ -59,40 +44,40 @@ describe('SessionManager', () => {
it('should fire an initialized trigger each time the card starts', async () => {
const card = await mount();
await vi.waitFor(() => expect(getStartedMessages(card)).toHaveLength(1));
await card.console.waitForMessage(CARD_INITIALIZED_MESSAGE);
// The card leaving the page is a change of the value the trigger watches,
// and must not fire it.
card.detach();
await card.updateComplete;
expect(getStartedMessages(card)).toHaveLength(1);
expect(card.console.countMessages(CARD_INITIALIZED_MESSAGE)).toBe(1);
card.attach();
await vi.waitFor(() => expect(getStartedMessages(card)).toHaveLength(2));
await card.console.waitForMessage(CARD_INITIALIZED_MESSAGE, { count: 2 });
});
it('should start the card again once Home Assistant comes back', async () => {
const card = await mount();
await vi.waitFor(() => expect(getStartedMessages(card)).toHaveLength(1));
await card.console.waitForMessage(CARD_INITIALIZED_MESSAGE);
// Losing Home Assistant changes the value the trigger watches, and must not
// fire it.
card.setConnected(false);
await card.updateComplete;
expect(getStartedMessages(card)).toHaveLength(1);
expect(card.console.countMessages(CARD_INITIALIZED_MESSAGE)).toBe(1);
card.setConnected(true);
await vi.waitFor(() => expect(getStartedMessages(card)).toHaveLength(2));
await card.console.waitForMessage(CARD_INITIALIZED_MESSAGE, { count: 2 });
});
it('should initialize the new cameras without starting the card again', async () => {
const card = await mount();
await card.events.waitForFirst('advanced-camera-card:media:loaded');
await vi.waitFor(() => expect(getStartedMessages(card)).toHaveLength(1));
await card.console.waitForMessage(CARD_INITIALIZED_MESSAGE);
// A camera change is the heaviest configuration change there is: the
// cameras are destroyed and initialized again.
@@ -107,7 +92,7 @@ describe('SessionManager', () => {
expect(getLoadedCameraIDs(card)).toContain(OTHER_CAMERA_ENTITY),
);
expect(getStartedMessages(card)).toHaveLength(1);
expect(card.console.countMessages(CARD_INITIALIZED_MESSAGE)).toBe(1);
});
it('should apply an override keyed on the card being started every time it starts', async () => {
@@ -127,7 +112,7 @@ describe('SessionManager', () => {
card.detach();
card.attach();
await vi.waitFor(() => expect(getStartedMessages(card)).toHaveLength(2));
await card.console.waitForMessage(CARD_INITIALIZED_MESSAGE, { count: 2 });
await card.waitForSelector('advanced-camera-card-menu');
});
@@ -142,7 +127,7 @@ describe('SessionManager', () => {
card.detach();
card.attach();
await vi.waitFor(() => expect(getStartedMessages(card)).toHaveLength(2));
await card.console.waitForMessage(CARD_INITIALIZED_MESSAGE, { count: 2 });
// A card that has been on screen once must not show the loading indicator
// again when it is re-attached.
tests/card-controller/issues/issues/initialization.browser.test.ts
+6 -19
View File
@@ -2,22 +2,20 @@ import { describe, expect, it, vi } from 'vitest';
import { MountedCard } from '../../../browser/mounted-card';
import {
CARD_INITIALIZED_MESSAGE,
createInitializedAutomation,
createStillCameraHASS,
createStillImageCameraConfig,
createStillImageCardConfig,
getBlockNotificationText,
} from '../../../browser/test-utils';
const STARTED_MESSAGE = 'card-started';
const INIT_FAILED_ISSUE_HEADING = 'Initialization failed';
// A camera Home Assistant has never heard of, which is what a typo in a
// configuration looks like and the earliest thing a camera can fail on.
const MISSING_CAMERA_ENTITY = 'camera.missing';
const getStartedMessages = (card: MountedCard): string[] =>
card.console.getMessages('info').filter((message) => message === STARTED_MESSAGE);
const getReportedInitializationFailures = (card: MountedCard): string[] =>
card.console
.getMessages('warn')
@@ -40,18 +38,7 @@ const mountBrokenCard = async (): Promise<MountedCard> =>
// Automatic retries switched off, so any recovery below can only be the
// retry control being used.
view: { issues: { retry_seconds: 0 } },
automations: [
{
triggers: [{ trigger: 'initialized' }],
actions: [
{
action: 'fire-dom-event',
advanced_camera_card_action: 'log',
message: STARTED_MESSAGE,
},
],
},
],
automations: [createInitializedAutomation()],
}),
createStillCameraHASS(),
);
@@ -63,7 +50,7 @@ describe('InitializationIssue', () => {
await waitForInitializationFailures(card);
// A card that failed to start has not started, whatever it is showing.
expect(getStartedMessages(card)).toHaveLength(0);
expect(card.console.countMessages(CARD_INITIALIZED_MESSAGE)).toBe(0);
// The camera the user meant now exists. Nothing recovers on its own from
// here: automatic retries are off, and a card showing a full-card issue
@@ -71,7 +58,7 @@ describe('InitializationIssue', () => {
card.setEntityState(MISSING_CAMERA_ENTITY, 'idle');
await card.clickControl('Retry');
await vi.waitFor(() => expect(getStartedMessages(card)).toHaveLength(1));
await card.console.waitForMessage(CARD_INITIALIZED_MESSAGE);
await card.events.waitForFirst('advanced-camera-card:media:loaded');
// Starting is not the same as the issue leaving the screen, since a
@@ -95,6 +82,6 @@ describe('InitializationIssue', () => {
);
await waitForInitializationFailures(card);
expect(getStartedMessages(card)).toHaveLength(0);
expect(card.console.countMessages(CARD_INITIALIZED_MESSAGE)).toBe(0);
});
});
tests/card-controller/keyboard-state-manager.browser.test.ts
+323
View File
@@ -0,0 +1,323 @@
import { assert, describe, expect, it } from 'vitest';
import type { LogActionConfig } from '../../src/config/schema/actions/custom/log';
import { createLogAction } from '../../src/utils/action';
import { MountedCard, type MountOptions } from '../browser/mounted-card';
import {
CARD_INITIALIZED_MESSAGE,
clickElement,
createInitializedAutomation,
createStillCameraHASS,
createStillImageCardConfig,
dispatchPointerDown,
getFocusedElement,
holdKey,
pressKey,
releaseKey,
} from '../browser/test-utils';
const ZOOM_ENTITY = 'input_boolean.zoom';
// What each automation writes when it runs, written as the pattern the console
// is later searched for. The console is the only place a `log` action reports
// to, and a message that names the automation is what makes one key press
// distinguishable from another.
const KEY_MESSAGE = /plain key press/;
const OTHER_CARD_KEY_MESSAGE = /key press on the other card/;
const CTRL_KEY_MESSAGE = /key press with ctrl held/;
const KEY_DOWN_MESSAGE = /key on the way down/;
const KEY_UP_MESSAGE = /key on the way up/;
const MENU_BUTTON_MESSAGE = /menu button pressed/;
const MENU_BUTTON_CONTROL = 'Log';
const EXPAND_CONTROL = 'Expand';
// The card's own builder, given the text its pattern matches.
const logAction = (regexp: RegExp): LogActionConfig => createLogAction(regexp.source);
interface MountCardOptions extends MountOptions {
// What a plain key press logs, so that a test with two cards on the page can
// tell which of them answered.
keyMessage?: RegExp;
}
const mountCard = async (options?: MountCardOptions): Promise<MountedCard> => {
const { keyMessage, ...mountOptions } = options ?? {};
const card = await MountedCard.create(
createStillImageCardConfig({
menu: { style: 'outside', buttons: { expand: { enabled: true } } },
elements: [
{
type: 'custom:advanced-camera-card-menu-icon',
icon: 'mdi:cow',
title: MENU_BUTTON_CONTROL,
tap_action: logAction(MENU_BUTTON_MESSAGE),
},
],
automations: [
createInitializedAutomation(),
{
triggers: [{ trigger: 'key', key: 'z' }],
actions: [logAction(keyMessage ?? KEY_MESSAGE)],
},
{
triggers: [{ trigger: 'key', key: 'b', ctrl: true }],
actions: [logAction(CTRL_KEY_MESSAGE)],
},
{
triggers: [{ trigger: 'key', key: 'w', state: 'down' }],
actions: [logAction(KEY_DOWN_MESSAGE)],
},
{
triggers: [{ trigger: 'key', key: 'w', state: 'up' }],
actions: [logAction(KEY_UP_MESSAGE)],
},
// A key whose action redraws the card, so a test can press a key, have
// the picture replaced under it, and press again.
{
triggers: [{ trigger: 'key', key: '1' }],
actions: [
{
action: 'fire-dom-event',
advanced_camera_card_action: 'ptz_digital',
absolute: { zoom: 3 },
},
],
},
// The same zoom driven by an entity rather than a key, so a test can
// zoom the card without pressing or clicking it first. A zoomed
// picture takes a press as the start of a pan, which is what such a
// test is about.
{
triggers: [{ trigger: 'state', entity: ZOOM_ENTITY, to: 'on' }],
actions: [
{
action: 'fire-dom-event',
advanced_camera_card_action: 'ptz_digital',
absolute: { zoom: 3 },
},
],
},
],
}),
createStillCameraHASS({ entities: { [ZOOM_ENTITY]: 'off' } }),
mountOptions,
);
await card.events.waitForFirst('advanced-camera-card:media:loaded');
return card;
};
// What the live view draws the camera into, which is the part of the card a
// user looks at and the largest part of it that is not a control.
const LIVE_MEDIA_SELECTOR = 'advanced-camera-card-live-provider';
const clickMedia = async (card: MountedCard): Promise<void> =>
await clickElement(await card.waitForSelector(LIVE_MEDIA_SELECTOR));
describe('KeyboardStateManager', () => {
it('should not act on a key until the card has been used', async () => {
const card = await mountCard();
// A key press belongs to whatever the user is looking at. A card that
// answered one aimed at something else on the dashboard would fire
// shortcuts nobody asked for.
await pressKey('z');
await clickMedia(card);
await pressKey('z');
await card.console.waitForMessage(KEY_MESSAGE);
// Once, from the press after the card was used. The first press is what
// this test is about, and only counting says it was ignored rather than
// merely slow.
expect(card.console.countMessages(KEY_MESSAGE)).toBe(1);
});
it('should keep receiving keys after an action has redrawn the card', async () => {
const card = await mountCard();
await clickMedia(card);
// The zoom replaces what is on screen, and the card is drawn again around
// it. Anything holding focus below the card would be thrown away here.
await pressKey('1');
await card.events.waitForFirst('advanced-camera-card:zoom:zoomed');
await pressKey('z');
await card.console.waitForMessage(KEY_MESSAGE);
});
it('should keep receiving keys after a menu button has been pressed', async () => {
const card = await mountCard();
await card.clickControl(MENU_BUTTON_CONTROL);
// The button did what it was asked, so nothing about claiming focus
// swallowed the press on its way in.
await card.console.waitForMessage(MENU_BUTTON_MESSAGE);
await pressKey('z');
await card.console.waitForMessage(KEY_MESSAGE);
});
it('should claim focus from a press that is consumed by the card', async () => {
const card = await mountCard();
card.setEntityState(ZOOM_ENTITY, 'on');
await card.events.waitForFirst('advanced-camera-card:zoom:zoomed');
// A press on a zoomed picture is taken as the start of a pan: it is kept
// from reaching anything else, and the browser is told not to do what it
// would normally do with it, which includes moving focus.
await clickMedia(card);
expect(getFocusedElement()).toBe(card.card);
await pressKey('z');
await card.console.waitForMessage(KEY_MESSAGE);
});
it('should not scroll the page when it takes focus', async () => {
// Well below the window, so the card is out of sight until the page is
// scrolled to it.
const card = await mountCard({ position: { top: '2000px' } });
window.scrollTo(0, 0);
// Pressed without a pointer: a real one is moved to what it presses, and
// where the page ends up is the thing being asserted on here.
dispatchPointerDown(await card.waitForSelector(LIVE_MEDIA_SELECTOR));
// The card is far below what is on screen. A user pressing a card they can
// only see part of would find the dashboard jumping under them.
expect(window.scrollY).toBe(0);
expect(getFocusedElement()).toBe(card.card);
});
it('should leave focus where it is when it is already inside the card', async () => {
const card = await mountCard();
await card.clickControl(MENU_BUTTON_CONTROL);
await card.console.waitForMessage(MENU_BUTTON_MESSAGE);
// Pressing a control puts focus on it rather than on the card around it,
// which is the situation this test is about.
const control = getFocusedElement();
assert(control);
expect(control).not.toBe(card.card);
let lostFocus = false;
control.addEventListener('focusout', () => (lostFocus = true));
await card.clickControl(MENU_BUTTON_CONTROL);
await card.console.waitForMessage(MENU_BUTTON_MESSAGE, { count: 2 });
// Taking focus off a control the user is working in is how a field being
// typed into loses what is in it, or a picker closes mid-choice.
expect(lostFocus).toBe(false);
expect(getFocusedElement()).toBe(control);
});
it('should hold on to a held key while a control in the card is pressed', async () => {
const card = await mountCard();
await clickMedia(card);
await holdKey('w');
await card.console.waitForMessage(KEY_DOWN_MESSAGE);
// Focus moves from the card to the button within it, which is not the user
// letting go of the key.
await card.clickControl(MENU_BUTTON_CONTROL);
await card.console.waitForMessage(MENU_BUTTON_MESSAGE);
// A key whose press was forgotten has no release either, which is what
// leaves a camera panning with nothing to stop it.
await releaseKey('w');
await card.console.waitForMessage(KEY_UP_MESSAGE);
});
it('should act on a key only when its modifiers match', async () => {
const card = await mountCard();
await clickMedia(card);
await pressKey('b');
// The trigger calls the modifier `ctrl`; the keyboard calls the key
// `Control`.
await holdKey('Control');
await pressKey('b');
await releaseKey('Control');
await card.console.waitForMessage(CTRL_KEY_MESSAGE);
// The press without the modifier is a different shortcut, and one this card
// has nothing configured for.
expect(card.console.countMessages(CTRL_KEY_MESSAGE)).toBe(1);
});
it('should keep receiving keys while expanded', async () => {
const card = await mountCard();
await card.clickControl(EXPAND_CONTROL);
// The whole card is drawn again inside a dialog, which is as large a
// change as anything that happens to it.
await card.waitForSelector('web-dialog');
await clickMedia(card);
await pressKey('z');
await card.console.waitForMessage(KEY_MESSAGE);
});
it('should stop receiving keys once it is taken out of the document', async () => {
const card = await mountCard();
await clickMedia(card);
await pressKey('z');
await card.console.waitForMessage(KEY_MESSAGE);
card.detach();
// A card on a dashboard tab that is not being looked at is out of the
// document, and answering keys from there would run shortcuts on a card
// nobody can see.
await pressKey('z');
expect(card.console.countMessages(KEY_MESSAGE)).toBe(1);
card.attach();
// The card builds itself again from nothing on its return, and answers
// nothing until it has.
await card.console.waitForMessage(CARD_INITIALIZED_MESSAGE, { count: 2 });
await clickMedia(card);
await pressKey('z');
await card.console.waitForMessage(KEY_MESSAGE, { count: 2 });
});
it('should not act on a key aimed at another card', async () => {
const card = await mountCard();
const otherCard = await mountCard({ keyMessage: OTHER_CARD_KEY_MESSAGE });
// Either ledger reports both cards, since there is only one console. Which
// card answered is in the message rather than in where it was read.
await clickMedia(card);
await pressKey('z');
await card.console.waitForMessage(KEY_MESSAGE);
await clickMedia(otherCard);
await pressKey('z');
await card.console.waitForMessage(OTHER_CARD_KEY_MESSAGE);
// One press each. A dashboard of cards that all answer every key press
// would run a shortcut once per card on screen.
expect(card.console.countMessages(KEY_MESSAGE)).toBe(1);
expect(card.console.countMessages(OTHER_CARD_KEY_MESSAGE)).toBe(1);
});
});