Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

fix(home): name the degraded and validating connect states

nirholasa13b779a84a4
diff --git a/.gitignore b/.gitignore
index 6cdc3b9e7..73f181948 100644
--- a/.gitignore
+++ b/.gitignore
@@ -551,6 +551,8 @@ download.zip
# not a directory, so the pattern above does not reach them. Same contents: the
# base URL and a working long-lived access token for the seeded house.
.ha-config-e2e-stack.json
+# One per concurrent home e2e lane, keyed by HOME_LIVE_NAME.
+.ha-config-e2e-stack.*.json
# Same thing at fleet scale: scripts/home-fleet.mjs boots numbered Home Assistant
# instances under .home-fleet/<n>/, each with its own token store.
.home-fleet/
diff --git a/src/home/connect.js b/src/home/connect.js
index fd05e9a9f..ac2f99d2f 100644
--- a/src/home/connect.js
+++ b/src/home/connect.js
@@ -29,7 +29,7 @@
import { isPrivateHost, normalizeBaseUrl } from '@three-ws/home-bridge/url';
import { disclosurePanel } from './disclosure-panel.js';
-import { renderManage } from './manage.js';
+import { isDegraded, renderManage } from './manage.js';
/** The eleven states. Each one has a designed treatment; none falls through. */
export const STATE = Object.freeze({
@@ -84,6 +84,14 @@ const root = document.getElementById('hm-root');
/** Session-lived only: never persisted, so a reload re-reads it from the server. */
let csrfToken = '';
+/**
+ * The screen currently on the page. State 3 (validating) is a property of one
+ * field rather than a different screen, so it is flipped on and off over this
+ * without re-rendering: rebuilding the card on a keystroke would take the caret
+ * out of the field the person is typing in.
+ */
+let renderedState = null;
+
boot();
async function boot() {
@@ -110,7 +118,21 @@ async function boot() {
function renderHomes(homes, notice) {
if (!homes.length) return render(STATE.EMPTY, notice ? { notice } : {});
- render(homes.length > 1 ? STATE.MANY : STATE.CONNECTED, { homes, ...(notice ? { notice } : {}) });
+ render(listState(homes), { homes, ...(notice ? { notice } : {}) });
+}
+
+/**
+ * Which of the list states this set of houses is in.
+ *
+ * The manage view renders all three identically on purpose (one list that
+ * scales), but the page still has to be able to say which one it is: a card
+ * reading "not answering right now" under `data-state="connected"` is the page
+ * disagreeing with itself, and it is the difference between state 9 being
+ * designed and state 9 being a paragraph.
+ */
+function listState(homes) {
+ if (homes.length > 1) return STATE.MANY;
+ return isDegraded(homes[0]) ? STATE.DEGRADED : STATE.CONNECTED;
}
/**
@@ -134,6 +156,7 @@ function sameHouse(storedBaseUrl, typedBaseUrl) {
*/
function render(state, data = {}) {
root.setAttribute('aria-busy', state === STATE.VERIFYING ? 'true' : 'false');
+ renderedState = state;
root.dataset.state = state;
clear(root);
@@ -251,9 +274,14 @@ function connectCard({ notice, values = {}, focus } = {}) {
// message appears under the field the moment the address is unreachable in
// principle, which is the only honest time to say it.
const liveValidate = () => {
+ const typed = url.input.value.trim();
const verdict = checkReachable(url.input.value);
- url.input.setAttribute('aria-invalid', verdict.ok || !url.input.value.trim() ? 'false' : 'true');
+ const invalid = Boolean(typed) && !verdict.ok;
+ url.input.setAttribute('aria-invalid', invalid ? 'true' : 'false');
setInlineError(url, verdict.ok ? '' : verdict.short);
+ // The page names the state it is in without rebuilding the card, so a
+ // keystroke never costs the caret and the state stays answerable.
+ root.dataset.state = invalid ? STATE.VALIDATING : renderedState;
};
url.input.addEventListener('input', liveValidate);
url.input.addEventListener('blur', liveValidate);
@@ -695,7 +723,7 @@ async function disconnect(home) {
title: `${home.label} is disconnected.`,
body: 'The access token we held has been erased. Delete the token in Home Assistant too if you want it gone on both sides, under ' + TOKEN_PATH + '.',
};
- if (homes && homes.length) render(homes.length > 1 ? STATE.MANY : STATE.CONNECTED, { homes, notice });
+ if (homes && homes.length) render(listState(homes), { homes, notice });
else render(STATE.REVOKED, { notice });
}
@@ -808,15 +836,25 @@ function field({ id, label, hint, value, attrs = {} }) {
input.value = value || '';
const hintEl = el('p', 'hm-hint', hint);
hintEl.id = `${id}-hint`;
+ // The hint is where inline validation speaks, so it announces its own
+ // changes. Without this a screen reader user types a LAN address, gets
+ // `aria-invalid` and no reason, and has to go looking for the sentence
+ // everybody else can see.
+ hintEl.setAttribute('aria-live', 'polite');
input.setAttribute('aria-describedby', hintEl.id);
wrap.append(labelEl, input, hintEl);
return { wrap, input, hint: hintEl, baseHint: hint };
}
-/** Inline, per-field validation text. Replaces the hint rather than stacking. */
+/**
+ * Inline, per-field validation text. Replaces the hint rather than stacking, and
+ * marks itself with an attribute rather than a colour: colour alone is not a
+ * message, and `[data-error]` is what both the stylesheet and a test can read.
+ */
function setInlineError(f, message) {
f.hint.textContent = message || f.baseHint;
- f.hint.style.color = message ? 'var(--hm-down)' : '';
+ if (message) f.hint.dataset.error = 'true';
+ else delete f.hint.dataset.error;
}
/**
diff --git a/src/home/manage.js b/src/home/manage.js
index 135b1b2d1..5e8671455 100644
--- a/src/home/manage.js
+++ b/src/home/manage.js
@@ -617,6 +617,23 @@ function isStale(home) {
return Date.now() - last > STALE_AFTER_MS;
}
+/**
+ * Is this house currently something other than live?
+ *
+ * The card already says so in words; this is the same judgement as a boolean,
+ * so the page can name the state it is in rather than reporting `connected`
+ * over a card that reads "not answering right now". Three ways a house is not
+ * live, and the card has a different sentence for each: it has stopped
+ * answering (stale), it is refusing the connection (unreachable), or the token
+ * we hold no longer works (auth_failed). `pending` is not degraded, it is the
+ * first few seconds of a connection that is still being made.
+ */
+export function isDegraded(home) {
+ if (!home) return false;
+ if (home.status === 'unreachable' || home.status === 'auth_failed') return true;
+ return isStale(home);
+}
+
function statusText(home, stale) {
if (stale) return `Last answered ${ago(home.last_ok_at)}. Showing the last state we saw.`;
switch (home.status) {
diff --git a/tests/e2e/home-connect-gallery.spec.js b/tests/e2e/home-connect-gallery.spec.js
new file mode 100644
index 000000000..01d6c5bbc
--- /dev/null
+++ b/tests/e2e/home-connect-gallery.spec.js
@@ -0,0 +1,203 @@
+/**
+ * Every screen of the /smart-home connect flow, at both ends of the viewport
+ * range, photographed and measured.
+ *
+ * The flow has fifteen states and the failure mode this guards is not a broken
+ * one: it is a state that was never opened. A screen only somebody's happy path
+ * reaches gets designed once and then drifts, and the first person to see it
+ * again is a stranger whose token was rejected at 320px.
+ *
+ * So this walks all fifteen in one run, writes a PNG of each at 1440px and at
+ * 320px into test-results/home-connect-states/, and asserts the thing a
+ * screenshot cannot: that no state overflows a 320px viewport sideways. The
+ * images are evidence for a human; the overflow measurement is the test.
+ *
+ * The API is stubbed (see home-connect-stubs.js) because a photograph of state
+ * 12 must not depend on a real plan ceiling being hit. Everything above the API
+ * boundary is the shipped page.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { expect, test } from '@playwright/test';
+
+import { CSRF, HOME, json, LIST, PAGE, SLOW, stub } from './home-connect-stubs.js';
+
+const OUT = path.join('test-results', 'home-connect-states');
+const DESKTOP = { width: 1440, height: 900 };
+const MOBILE = { width: 320, height: 720 };
+
+const root = (page) => page.locator('#hm-root');
+
+fs.mkdirSync(OUT, { recursive: true });
+
+/**
+ * One screen, reached the way a person reaches it, then photographed at both
+ * widths and measured at the narrow one.
+ *
+ * @param {string} name the file stem, prefixed with the state's number
+ * @param {(page: import('@playwright/test').Page) => Promise<void>} reach
+ * @param {string} expected the `data-state` the page must be in when it lands
+ */
+function screen(name, expected, reach) {
+ test(`${name} renders, and fits a 320px screen`, async ({ page }) => {
+ await page.setViewportSize(DESKTOP);
+ await reach(page);
+ await expect(root(page)).toHaveAttribute('data-state', expected, { timeout: SLOW });
+ await page.screenshot({ path: path.join(OUT, `${name}-1440.png`), fullPage: true });
+
+ await page.setViewportSize(MOBILE);
+ // The reflow is a layout pass, not an animation: waiting on the measured
+ // width rather than a timeout keeps this honest on a slow machine.
+ await expect
+ .poll(() => page.evaluate(() => document.documentElement.clientWidth), { timeout: 10_000 })
+ .toBe(MOBILE.width);
+ await page.screenshot({ path: path.join(OUT, `${name}-320.png`), fullPage: true });
+
+ const overflow = await page.evaluate(() => document.documentElement.scrollWidth - document.documentElement.clientWidth);
+ expect(overflow, `${name} pushes the page sideways at 320px`).toBeLessThanOrEqual(0);
+ });
+}
+
+/** A house whose label is longer than any column, to prove truncation. */
+const LONG = {
+ ...HOME,
+ id: '7d1e2f30-4a5b-4c6d-8e9f-0a1b2c3d4e5f',
+ label: 'The house at the end of the very long road that somebody typed the whole name of',
+ base_url: 'https://a-very-long-subdomain-somebody-actually-uses.duckdns.example.com',
+};
+
+test.describe('/smart-home, every state', () => {
+ screen('01-signed-out', 'signed_out', async (page) => {
+ await page.route(LIST, (route) => route.fulfill(json({ error: 'unauthorized' }, 401)));
+ await page.goto(PAGE);
+ });
+
+ screen('02-empty', 'empty', async (page) => {
+ await stub(page);
+ await page.goto(PAGE);
+ });
+
+ screen('03-validating', 'validating', async (page) => {
+ await stub(page);
+ await page.goto(PAGE);
+ await expect(page.locator('#hm-url')).toBeVisible({ timeout: SLOW });
+ await page.locator('#hm-url').fill('http://homeassistant.local:8123');
+ await page.locator('#hm-url').blur();
+ });
+
+ screen('04-private-host', 'private_host', async (page) => {
+ await stub(page);
+ await page.goto(PAGE);
+ await expect(page.locator('#hm-url')).toBeVisible({ timeout: SLOW });
+ await page.fill('#hm-label', 'Home');
+ await page.fill('#hm-url', 'http://192.168.1.10:8123');
+ await page.fill('#hm-token', 'never-sent');
+ await page.click('button[type="submit"]');
+ });
+
+ screen('05-verifying', 'verifying', async (page) => {
+ // A connect that never answers: this is the state as a person on a slow
+ // house actually sees it, held still long enough to be photographed.
+ await stub(page, { onConnect: () => new Promise(() => {}) });
+ await page.goto(PAGE);
+ await expect(page.locator('#hm-url')).toBeVisible({ timeout: SLOW });
+ await page.fill('#hm-label', 'Home');
+ await page.fill('#hm-url', 'https://home.example.com');
+ await page.fill('#hm-token', 'a-token');
+ await page.click('button[type="submit"]');
+ });
+
+ screen('06-connected', 'connected', async (page) => {
+ await stub(page, { homes: [HOME] });
+ await page.goto(PAGE);
+ });
+
+ screen('07-auth-failed', 'auth_failed', async (page) => {
+ await stub(page, { onConnect: () => json({ code: 'auth', message: 'Home Assistant rejected that token.' }, 401) });
+ await page.goto(PAGE);
+ await expect(page.locator('#hm-url')).toBeVisible({ timeout: SLOW });
+ await page.fill('#hm-label', 'Home');
+ await page.fill('#hm-url', 'https://home.example.com');
+ await page.fill('#hm-token', 'a-stale-token');
+ await page.click('button[type="submit"]');
+ });
+
+ screen('08-unreachable', 'unreachable', async (page) => {
+ await stub(page, { onConnect: () => json({ code: 'unreachable', message: 'home.example.com did not answer.' }, 502) });
+ await page.goto(PAGE);
+ await expect(page.locator('#hm-url')).toBeVisible({ timeout: SLOW });
+ await page.fill('#hm-label', 'Home');
+ await page.fill('#hm-url', 'https://home.example.com');
+ await page.fill('#hm-token', 'a-token');
+ await page.click('button[type="submit"]');
+ });
+
+ screen('09-degraded', 'degraded', async (page) => {
+ const twoHoursAgo = new Date(Date.now() - 2 * 60 * 60 * 1000).toISOString();
+ await stub(page, { homes: [{ ...HOME, last_ok_at: twoHoursAgo }] });
+ await page.goto(PAGE);
+ });
+
+ screen('10-revoked', 'revoked', async (page) => {
+ let disconnected = false;
+ await page.route(CSRF, (route) => route.fulfill(json({ token: 'csrf-test-token' })));
+ await page.route(LIST, (route) => route.fulfill(json({ homes: disconnected ? [] : [HOME] })));
+ await page.route(`**/api/home/${HOME.id}`, (route) => {
+ disconnected = true;
+ return route.fulfill(json({ ok: true }));
+ });
+ await page.goto(PAGE);
+ await expect(root(page)).toHaveAttribute('data-state', 'connected', { timeout: SLOW });
+ await page.getByRole('button', { name: /disconnect/i }).first().click();
+ await page.getByRole('button', { name: /disconnect .* erase/i }).click();
+ });
+
+ screen('11-many-homes', 'many', async (page) => {
+ await stub(page, {
+ homes: [
+ HOME,
+ LONG,
+ { ...HOME, id: '3c4d5e6f-7a8b-49cd-8e0f-1a2b3c4d5e6f', label: 'The office', status: 'unreachable', status_detail: 'Not answering right now.' },
+ { ...HOME, id: '4d5e6f70-8b9c-4ade-9f01-2b3c4d5e6f70', label: 'The cabin', status: 'auth_failed', status_detail: 'Home Assistant rejected the stored token.' },
+ ],
+ });
+ await page.goto(PAGE);
+ });
+
+ screen('12-quota-reached', 'quota_reached', async (page) => {
+ await stub(page, {
+ homes: [HOME],
+ onConnect: () => json({ code: 'quota', message: 'Your plan covers one home.', quota: { limit: 1, used: 1, tier: 'free', upgrade: '/pricing' } }, 402),
+ });
+ await page.goto(PAGE);
+ await expect(root(page)).toHaveAttribute('data-state', 'connected', { timeout: SLOW });
+ await page.getByRole('button', { name: /connect another home/i }).click();
+ await page.fill('#hm-label', 'The cabin');
+ await page.fill('#hm-url', 'https://cabin.example.com');
+ await page.fill('#hm-token', 'a-token');
+ await page.click('button[type="submit"]');
+ });
+
+ screen('13-pairing', 'pairing', async (page) => {
+ await stub(page);
+ await page.goto(PAGE);
+ await expect(page.locator('#hm-url')).toBeVisible({ timeout: SLOW });
+ await page.fill('#hm-label', 'Home');
+ await page.fill('#hm-url', 'http://192.168.1.10:8123');
+ await page.fill('#hm-token', 'never-sent');
+ await page.click('button[type="submit"]');
+ await page.getByRole('button', { name: /only on my network/i }).click();
+ });
+
+ screen('14-one-home', 'one_home', async (page) => {
+ await stub(page, { homes: [HOME, LONG] });
+ await page.goto(`/smart-home/${HOME.id}/settings`);
+ });
+
+ screen('15-not-found', 'not_found', async (page) => {
+ await stub(page, { homes: [HOME] });
+ await page.goto('/smart-home/00000000-0000-4000-8000-000000000000/settings');
+ });
+});
diff --git a/tests/e2e/home-connect-stubs.js b/tests/e2e/home-connect-stubs.js
new file mode 100644
index 000000000..64c3cf037
--- /dev/null
+++ b/tests/e2e/home-connect-stubs.js
@@ -0,0 +1,54 @@
+/**
+ * The fixtures behind the /smart-home connect flow's browser specs.
+ *
+ * Shared by two specs that need the same twelve screens for different reasons:
+ * home-connect.spec.js asserts behaviour on them, home-connect-gallery.spec.js
+ * photographs them at 1440px and 320px. Keeping one copy of the stub means a
+ * screen can never be asserted in one shape and captured in another.
+ *
+ * Everything stubbed here is the API boundary and nothing below it: the page,
+ * the controller, the manage view and the reachability rules are all the
+ * shipped code. The live counterpart, which stubs nothing at all and drives a
+ * real Home Assistant, is home-connect-live.spec.js.
+ */
+
+export const PAGE = '/smart-home';
+export const LIST = '**/api/home';
+export const CSRF = '**/api/csrf-token';
+export const STATUS = '**/api/status';
+
+/** First hit transforms this page's module graph through the dev server. */
+export const SLOW = 60_000;
+
+/** A house as the API returns it, measured against a real instance. */
+export const HOME = {
+ id: '2b0d4c7e-1f8a-4c3d-9e11-7a6b5c4d3e2f',
+ label: 'Home',
+ base_url: 'https://home.example.com',
+ transport: 'direct',
+ relay_id: null,
+ status: 'connected',
+ status_detail: null,
+ capabilities: { websocket: true, entityCount: 120, areaCount: 3, floorCount: 1, macroCount: 2, haVersion: '2026.9.0', mcp: false, mcpToolCount: 0 },
+ last_ok_at: new Date().toISOString(),
+ last_error_at: null,
+ created_at: new Date().toISOString(),
+ updated_at: new Date().toISOString(),
+ revoked_at: null,
+};
+
+export function json(body, status = 200) {
+ return { status, contentType: 'application/json', body: JSON.stringify(body) };
+}
+
+/** Everything the page reads, with the home list under the caller's control. */
+export async function stub(page, { homes = [], onConnect } = {}) {
+ await page.route(CSRF, (route) => route.fulfill(json({ token: 'csrf-test-token', data: { token: 'csrf-test-token' } })));
+ await page.route(LIST, async (route) => {
+ if (route.request().method() === 'POST') {
+ const body = JSON.parse(route.request().postData() || '{}');
+ return route.fulfill(onConnect ? onConnect(body) : json({ home: HOME, capabilities: HOME.capabilities }, 201));
+ }
+ return route.fulfill(json({ homes }));
+ });
+}
diff --git a/tests/e2e/home-connect.spec.js b/tests/e2e/home-connect.spec.js
index f42d0c469..eb90a198f 100644
--- a/tests/e2e/home-connect.spec.js
+++ b/tests/e2e/home-connect.spec.js
@@ -31,44 +31,7 @@
import { expect, test } from '@playwright/test';
-const PAGE = '/smart-home';
-const LIST = '**/api/home';
-const CSRF = '**/api/csrf-token';
-
-// First hit transforms this page's module graph through the dev server.
-const SLOW = 60_000;
-
-const HOME = {
- id: '2b0d4c7e-1f8a-4c3d-9e11-7a6b5c4d3e2f',
- label: 'Home',
- base_url: 'https://home.example.com',
- transport: 'direct',
- relay_id: null,
- status: 'connected',
- status_detail: null,
- capabilities: { websocket: true, entityCount: 120, areaCount: 3, floorCount: 1, macroCount: 2, haVersion: '2026.9.0', mcp: false, mcpToolCount: 0 },
- last_ok_at: new Date().toISOString(),
- last_error_at: null,
- created_at: new Date().toISOString(),
- updated_at: new Date().toISOString(),
- revoked_at: null,
-};
-
-function json(body, status = 200) {
- return { status, contentType: 'application/json', body: JSON.stringify(body) };
-}
-
-/** Everything the page reads, with the home list under the caller's control. */
-async function stub(page, { homes = [], onConnect } = {}) {
- await page.route(CSRF, (route) => route.fulfill(json({ token: 'csrf-test-token', data: { token: 'csrf-test-token' } })));
- await page.route(LIST, async (route) => {
- if (route.request().method() === 'POST') {
- const body = JSON.parse(route.request().postData() || '{}');
- return route.fulfill(onConnect ? onConnect(body) : json({ home: HOME, capabilities: HOME.capabilities }, 201));
- }
- return route.fulfill(json({ homes }));
- });
-}
+import { CSRF, HOME, json, LIST, PAGE, SLOW, stub } from './home-connect-stubs.js';
const state = (page) => page.locator('#hm-root');
@@ -119,6 +82,37 @@ test.describe('/smart-home connect flow', () => {
await expect(page.getByRole('listitem').filter({ hasText: /dial out to three\.ws/i })).toBeVisible();
});
+ test('typing a LAN address names the state and says so under the field', async ({ page }) => {
+ // State 3 is the one that is easiest to leave implicit: an inline message
+ // with the page still calling itself `empty`. Naming it is what makes it
+ // assertable from outside, and the caret has to survive it, because a
+ // validation that re-rendered the card would eject the person mid-word.
+ await stub(page);
+ await page.goto(PAGE);
+ await expect(state(page)).toHaveAttribute('data-state', 'empty', { timeout: SLOW });
+
+ const sent = [];
+ page.on('request', (r) => { if (r.url().includes('/api/')) sent.push(r.url()); });
+
+ const url = page.locator('#hm-url');
+ await url.click();
+ await page.keyboard.type('http://192.168.1.10:8123');
+
+ await expect(state(page)).toHaveAttribute('data-state', 'validating');
+ await expect(url).toHaveAttribute('aria-invalid', 'true');
+ await expect(page.locator('#hm-url-hint')).toContainText(/only on your home network/i);
+ await expect(page.locator('#hm-url-hint')).toHaveAttribute('data-error', 'true');
+ // The caret is still where they were typing, so the next keystroke lands.
+ await expect(url).toBeFocused();
+ expect(sent, 'validating as they type must cost nothing on the network').toEqual([]);
+
+ // And it lets go again the moment the address becomes usable.
+ await url.fill('https://home.example.com');
+ await expect(state(page)).toHaveAttribute('data-state', 'empty');
+ await expect(url).toHaveAttribute('aria-invalid', 'false');
+ await expect(page.locator('#hm-url-hint')).not.toHaveAttribute('data-error', 'true');
+ });
+
test('a rejected token says so and puts focus back in the token field', async ({ page }) => {
await stub(page, {
onConnect: () => json({ error: 'auth', code: 'auth', message: 'Home Assistant rejected that access token.' }, 400),
@@ -251,7 +245,10 @@ test.describe('/smart-home connect flow', () => {
const twoHoursAgo = new Date(Date.now() - 2 * 60 * 60 * 1000).toISOString();
await stub(page, { homes: [{ ...HOME, last_ok_at: twoHoursAgo }] });
await page.goto(PAGE);
- await expect(state(page)).toHaveAttribute('data-state', 'connected', { timeout: SLOW });
+ // The page names it degraded rather than connected. A card that reads
+ // "not answering" under `data-state="connected"` is the page disagreeing
+ // with itself, and it is what made state 9 unassertable from outside.
+ await expect(state(page)).toHaveAttribute('data-state', 'degraded', { timeout: SLOW });
// The card is still there, and it says how long ago the house last spoke.
await expect(page.locator('.hm-card')).toHaveCount(1);
@@ -275,7 +272,7 @@ test.describe('/smart-home connect flow', () => {
test('a rejected stored token explains itself in the list', async ({ page }) => {
await stub(page, { homes: [{ ...HOME, status: 'auth_failed', status_detail: 'Home Assistant rejected the stored token.', last_ok_at: null }] });
await page.goto(PAGE);
- await expect(state(page)).toHaveAttribute('data-state', 'connected', { timeout: SLOW });
+ await expect(state(page)).toHaveAttribute('data-state', 'degraded', { timeout: SLOW });
await expect(page.locator('.hm-status')).toContainText(/rejected the stored token/i);
await expect(page.locator('.hm-dot-auth_failed')).toBeVisible();
diff --git a/tests/e2e/home-global-setup.js b/tests/e2e/home-global-setup.js
index 6f66feb4c..aae26e6bb 100644
--- a/tests/e2e/home-global-setup.js
+++ b/tests/e2e/home-global-setup.js
@@ -30,14 +30,24 @@ import { acquireHomeInstance } from '../_helpers/home-instance.js';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
-/** Where the stack's details land. Gitignored: it holds a real access token. */
-export const STACK_FILE = path.join(ROOT, '.ha-config-e2e-stack.json');
+/**
+ * Where the stack's details land. Gitignored: it holds a real access token.
+ *
+ * Keyed by HOME_LIVE_NAME, the same name that already gives each lane its own
+ * Home Assistant container. This worktree is shared by concurrent agents and
+ * more than one home run is often in flight at once; a single shared path meant
+ * the last setup to finish silently repointed every other run at ITS house, and
+ * the specs then drove the wrong Home Assistant while reporting product bugs.
+ * One file per lane costs nothing and removes the whole class.
+ */
+export const LANE = process.env.HOME_LIVE_NAME || 'e2e';
+export const STACK_FILE = path.join(ROOT, `.ha-config-e2e-stack${LANE === 'e2e' ? '' : `.${LANE}`}.json`);
/** The reusable QA accounts. Gitignored: real credentials for a real account. */
const ACCOUNTS_FILE = path.join(ROOT, '.ha-config-e2e-accounts.json');
export default async function globalSetup(config) {
process.env.HOME_LIVE = process.env.HOME_LIVE || '1';
- process.env.HOME_LIVE_NAME = process.env.HOME_LIVE_NAME || 'e2e';
+ process.env.HOME_LIVE_NAME = process.env.HOME_LIVE_NAME || LANE;
const origin = config?.projects?.[0]?.use?.baseURL || 'http://localhost:3020';
@@ -47,7 +57,7 @@ export default async function globalSetup(config) {
const accounts = await ensureAccounts(origin);
fs.writeFileSync(
STACK_FILE,
- `${JSON.stringify({ home, accounts, origin, startedAt: new Date().toISOString() }, null, '\t')}\n`,
+ `${JSON.stringify({ home, accounts, origin, lane: LANE, startedAt: new Date().toISOString() }, null, '\t')}\n`,
);
console.log(`[home-e2e] accounts ready: ${accounts.owner.username}, ${accounts.guest.username}`);
}
diff --git a/tests/e2e/home-support.js b/tests/e2e/home-support.js
index a1a6f22fd..9f205dfa8 100644
--- a/tests/e2e/home-support.js
+++ b/tests/e2e/home-support.js
@@ -60,18 +60,44 @@ export async function signIn(page, role = 'owner') {
return account;
}
+/** Every home on the signed-in account, however the endpoint shapes its list. */
+async function listHomes(page) {
+ const list = await page.request.get('/api/home', { timeout: 60_000 });
+ if (!list.ok()) return [];
+ const body = await list.json().catch(() => null);
+ return Array.isArray(body?.homes) ? body.homes : Array.isArray(body) ? body : [];
+}
+
+/** The base URL of a listed home, whichever spelling the payload uses. */
+function homeBaseUrl(home) {
+ return String(home?.baseUrl || home?.base_url || '').replace(/\/+$/, '');
+}
+
/**
- * Take every home this account has off the platform.
+ * The homes on this account that point at THIS lane's Home Assistant.
+ *
+ * Concurrent agents share this worktree and this QA account, and more than one
+ * home lane is routinely in flight at once. A helper that treated every home on
+ * the account as its own deleted the house a peer run was mid-journey inside,
+ * and then opened whichever house won the race, so both runs failed reporting
+ * product bugs that were never there. Each lane owns exactly the houses on its
+ * own container and leaves the rest alone.
+ */
+async function laneHomes(page) {
+ const mine = homeBaseUrl(homeInstance());
+ return (await listHomes(page)).filter((home) => homeBaseUrl(home) === mine);
+}
+
+/**
+ * Take this lane's homes off the platform.
*
* Journeys grant standing permissions on locks, and a grant surviving into the
* next journey would quietly disarm the gate that journey is trying to prove.
- * Each one therefore starts from an account with no houses on it.
+ * Each one therefore starts from an account with no houses of ITS OWN on it;
+ * a concurrent lane's houses are none of its business.
*/
export async function resetHomes(page) {
- const list = await page.request.get('/api/home', { timeout: 60_000 });
- if (!list.ok()) return 0;
- const body = await list.json().catch(() => null);
- const homes = Array.isArray(body?.homes) ? body.homes : Array.isArray(body) ? body : [];
+ const homes = await laneHomes(page);
for (const home of homes) {
await page.request.delete(`/api/home/${home.id}`, { timeout: 60_000 }).catch(() => {});
}
@@ -86,11 +112,16 @@ export async function resetHomes(page) {
*/
export async function connectHome(page, { label = 'The lane house' } = {}) {
const home = homeInstance();
+ // Two agents running the SAME spec on this shared account would otherwise
+ // both connect a house called "Journey nine" and each would then assert on
+ // the other's. The lane name is already what separates their containers.
+ const lane = stack().lane;
+ const scoped = lane && lane !== 'e2e' ? `${label} ${lane}` : label;
await page.goto('/smart-home', { waitUntil: 'domcontentloaded' });
await expect(page.locator('#hm-url')).toBeVisible({ timeout: 60_000 });
- await page.fill('#hm-label', label);
+ await page.fill('#hm-label', scoped);
await page.fill('#hm-url', home.baseUrl);
await page.fill('#hm-token', home.token);
await page.getByRole('button', { name: 'Connect this home' }).click();
@@ -98,8 +129,8 @@ export async function connectHome(page, { label = 'The lane house' } = {}) {
// The connected state is the one that lists rooms. Waiting for the room list
// rather than for a spinner to vanish means the assertion is about the house
// having been read, not about an animation having finished.
- await expect(page.getByText(label, { exact: false }).first()).toBeVisible({ timeout: 120_000 });
- return label;
+ await expect(page.getByText(scoped, { exact: false }).first()).toBeVisible({ timeout: 120_000 });
+ return scoped;
}
/**
@@ -111,10 +142,10 @@ export async function connectHome(page, { label = 'The lane house' } = {}) {
* "Unlock Front Door" instead of on a guessed pixel of a WebGL canvas.
*/
export async function openScene(page) {
- const list = await page.request.get('/api/home', { timeout: 60_000 });
- const body = await list.json();
- const homes = Array.isArray(body?.homes) ? body.homes : Array.isArray(body) ? body : [];
- if (!homes.length) throw new Error('no connected home to open');
+ const homes = await laneHomes(page);
+ if (!homes.length) {
+ throw new Error(`no connected home on this lane's house (${homeBaseUrl(homeInstance())}) to open`);
+ }
await page.goto(`/smart-home/${homes[0].id}`, { waitUntil: 'domcontentloaded' });
const flat = page.locator('#hs-view-2d');