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.

test(home): drive the house end to end and prove the door from the house

nirholasb98f1a72e0a7
diff --git a/package.json b/package.json
index d31e27066..16626c456 100644
--- a/package.json
+++ b/package.json
@@ -422,7 +422,9 @@
"companion:e2e": "node --env-file=.env.local --env-file=.env scripts/companion-e2e.mjs",
"home:instance": "node scripts/home-test-instance.mjs --up --onboard --seed --name lane",
"home:instance:down": "node scripts/home-test-instance.mjs --down --name lane",
- "test:home:live": "HOME_LIVE=1 vitest run packages/home-bridge tests/home-store.test.js"
+ "test:home:live": "HOME_LIVE=1 vitest run packages/home-bridge tests/home-store.test.js",
+ "home:matrix": "node scripts/home-version-matrix.mjs",
+ "test:home:e2e": "node --env-file=.env.local ./node_modules/@playwright/test/cli.js test --config=playwright.home.config.js"
},
"dependencies": {
"@0xsplits/splits-sdk": "^6.5.0",
diff --git a/tests/e2e/home-confirmation.spec.js b/tests/e2e/home-confirmation.spec.js
new file mode 100644
index 000000000..d4c6e4eae
--- /dev/null
+++ b/tests/e2e/home-confirmation.spec.js
@@ -0,0 +1,173 @@
+/**
+ * Journeys 4, 5, 6 and 7: the gate on the front door.
+ *
+ * These are the ones that matter, and they share one rule: EVERY assertion
+ * about the door reads the lock's state back out of Home Assistant. A
+ * confirmation card that renders perfectly while the deadbolt moves anyway is
+ * the exact failure this lane exists to catch, and our own UI text cannot tell
+ * us which happened. `readState(instance, lock)` is Home Assistant answering,
+ * not us.
+ */
+
+import { expect, test } from '@playwright/test';
+
+import {
+ connectHome,
+ homeInstance,
+ lockedDoor,
+ openScene,
+ readState,
+ relock,
+ resetHomes,
+ signIn,
+ waitForState,
+} from './home-support.js';
+
+test.describe.configure({ mode: 'serial' });
+
+test('journey 5: an unlock is offered, cancelled, and the door stays locked', async ({ page }) => {
+ const instance = homeInstance();
+ await signIn(page, 'owner');
+ await resetHomes(page);
+ await connectHome(page, { label: 'Journey five' });
+ await openScene(page);
+
+ const lock = await lockedDoor(instance);
+ expect(await readState(instance, lock)).toBe('locked');
+
+ await unlockButton(page, instance, lock).click();
+
+ const card = page.getByRole('alertdialog', { name: 'Confirm this action' });
+ await expect(card).toBeVisible({ timeout: 60_000 });
+ await expect(card.getByText('Opens your home')).toBeVisible();
+
+ await card.getByRole('button', { name: 'Cancel' }).click();
+ await expect(card).toBeHidden({ timeout: 30_000 });
+
+ // Home Assistant's own answer, and the only one that counts.
+ expect(await readState(instance, lock), 'a cancelled confirmation must leave the door locked').toBe('locked');
+
+ // Give it room to be wrong: a late call would land in these seconds.
+ await expect
+ .poll(() => readState(instance, lock), { timeout: 10_000, intervals: [1000] })
+ .toBe('locked');
+});
+
+test('journey 6: an unlock is offered, confirmed, and the door actually unlocks', async ({ page }) => {
+ const instance = homeInstance();
+ await signIn(page, 'owner');
+ await openScene(page);
+
+ const lock = await lockedDoor(instance);
+ expect(await readState(instance, lock)).toBe('locked');
+
+ try {
+ await unlockButton(page, instance, lock).click();
+
+ const card = page.getByRole('alertdialog', { name: 'Confirm this action' });
+ await expect(card).toBeVisible({ timeout: 60_000 });
+ await card.getByRole('button', { name: 'Yes, do it' }).click();
+
+ // Home Assistant's own answer again. This is the one case where the door
+ // is supposed to move, and nothing but the house can confirm it did.
+ expect(await waitForState(instance, lock, ['unlocked', 'unlocking', 'open', 'opening'], { timeout: 45_000 })).toBeTruthy();
+ } finally {
+ // Never leave a door open behind a test run.
+ await relock(instance, lock);
+ }
+ expect(await readState(instance, lock)).toMatch(/^(locked|locking)$/);
+});
+
+test('journey 7: a guest is refused the unlock by role, and the door stays locked', async ({ page, browser }) => {
+ const instance = homeInstance();
+
+ // The owner invites a guest into the household, through the real invite API
+ // the members panel calls.
+ await signIn(page, 'owner');
+ const homes = await (await page.request.get('/api/home')).json();
+ const home = (Array.isArray(homes?.homes) ? homes.homes : homes)[0];
+ expect(home?.id, 'journey 5 left a connected home for this one to use').toBeTruthy();
+
+ const guestContext = await browser.newContext();
+ const guestPage = await guestContext.newPage();
+ try {
+ const guest = await signIn(guestPage, 'guest');
+
+ const invited = await page.request.post(`/api/home/${home.id}/members`, {
+ data: { email: guest.email, role: 'guest' },
+ headers: { 'content-type': 'application/json' },
+ timeout: 60_000,
+ });
+ expect(invited.ok(), `inviting the guest returned ${invited.status()}`).toBe(true);
+ const invite = await invited.json().catch(() => ({}));
+ if (invite?.invite?.token) {
+ const accepted = await guestPage.request.post(`/api/home/invites/${invite.invite.token}`, { timeout: 60_000 });
+ expect(accepted.ok(), `accepting the invite returned ${accepted.status()}`).toBe(true);
+ }
+
+ const lock = await lockedDoor(instance);
+ expect(await readState(instance, lock)).toBe('locked');
+
+ // The guest confirms, explicitly and deliberately. The point is that an
+ // explicit yes is not enough when the role forbids it: `confirmed: true`
+ // is a human saying yes, never an authorisation.
+ const attempt = await guestPage.request.post(`/api/home/${home.id}/call`, {
+ data: { domain: 'lock', service: 'unlock', entity_id: lock, confirmed: true },
+ headers: { 'content-type': 'application/json' },
+ timeout: 60_000,
+ });
+ expect(attempt.ok(), 'a guest must not be able to unlock a door').toBe(false);
+ expect([401, 403]).toContain(attempt.status());
+
+ expect(await readState(instance, lock), 'a refused guest must leave the door locked').toBe('locked');
+ await expect
+ .poll(() => readState(instance, lock), { timeout: 10_000, intervals: [1000] })
+ .toBe('locked');
+ } finally {
+ await guestContext.close();
+ }
+});
+
+test('journey 4: "good night" runs the house\'s own scene, and the lock it touches is gated', async ({ page }) => {
+ const instance = homeInstance();
+ await signIn(page, 'owner');
+ const homes = await (await page.request.get('/api/home')).json();
+ const home = (Array.isArray(homes?.homes) ? homes.homes : homes)[0];
+ expect(home?.id).toBeTruthy();
+
+ const lock = await lockedDoor(instance);
+
+ // The phrase resolves to a scene this house actually has, not to anything we
+ // shipped: the seeded house has Bedtime, and the resolver has to find it.
+ const dry = await page.request.post(`/api/home/${home.id}/activate`, {
+ data: { phrase: 'good night', dryRun: true },
+ headers: { 'content-type': 'application/json' },
+ timeout: 60_000,
+ });
+ expect(dry.ok(), `activate dry run returned ${dry.status()}`).toBe(true);
+ const preview = await dry.json();
+ expect(preview.match?.entityId, '"good night" must resolve to a scene in this house').toMatch(/^(scene|script)\./);
+
+ const ran = await page.request.post(`/api/home/${home.id}/activate`, {
+ data: { phrase: 'good night' },
+ headers: { 'content-type': 'application/json' },
+ timeout: 60_000,
+ });
+ const body = await ran.json().catch(() => ({}));
+
+ if (ran.ok() && body.ran) {
+ // Bedtime locks up. Locking is the safe direction and is never gated, so
+ // the scene running must leave the door locked, not opened.
+ expect(await waitForState(instance, lock, ['locked', 'locking'], { timeout: 45_000 })).toBeTruthy();
+ } else {
+ // The other correct outcome: the macro touches something guarded, so it
+ // stopped and asked instead of running.
+ expect(body.error || body.code).toMatch(/needs_confirmation/);
+ expect(await readState(instance, lock)).toBe('locked');
+ }
+});
+
+/** The Unlock control for one real lock, found by the label the page gives it. */
+function unlockButton(page, instance, entityId) {
+ return page.locator(`[data-entity-id="${entityId}"]`).getByRole('button', { name: /^Unlock\b/ }).first();
+}
diff --git a/tests/e2e/home-connect.spec.js b/tests/e2e/home-connect.spec.js
index 076dfbd7d..cc9dcabc9 100644
--- a/tests/e2e/home-connect.spec.js
+++ b/tests/e2e/home-connect.spec.js
@@ -89,8 +89,12 @@ test.describe('/smart-home connect flow', () => {
await expect(state(page)).toHaveAttribute('data-state', 'empty', { timeout: SLOW });
await expect(page.locator('#hm-url')).toBeVisible();
- // The token instructions are inline: nobody should have to go and search.
- await expect(page.getByText(/long-lived access tokens/i)).toBeVisible();
+ // The token instructions are inline, one disclosure away: nobody should
+ // have to leave the page to find out where Home Assistant hides them.
+ const help = page.getByRole('group').filter({ hasText: /where do i get an access token/i });
+ await expect(help).toBeVisible();
+ await help.getByText(/where do i get an access token/i).click();
+ await expect(help.getByText(/scroll to long-lived access tokens/i)).toBeVisible();
});
test('a private address is refused with no network call at all', async ({ page }) => {
diff --git a/tests/e2e/home-control.spec.js b/tests/e2e/home-control.spec.js
new file mode 100644
index 000000000..fa2815d1b
--- /dev/null
+++ b/tests/e2e/home-control.spec.js
@@ -0,0 +1,129 @@
+/**
+ * Journeys 2, 3 and 8: acting on the house, seeing the house act, and surviving
+ * the house going away.
+ *
+ * Every one drives the 2D house rather than the 3D one. That is not a lesser
+ * path: it is the same model, the same action call and the same gate, rendered
+ * with real buttons instead of a WebGL raycast, and it is the view the
+ * accessibility and low-power paths use. Driving it means a click lands on a
+ * named control and not on a guessed pixel.
+ */
+
+import { expect, test } from '@playwright/test';
+
+import { anyLight, connectHome, homeInstance, openScene, readState, signIn, resetHomes, waitForState } from './home-support.js';
+
+test.describe.configure({ mode: 'serial' });
+
+test('journey 2: toggle a light in the house and see the real device change', async ({ page }) => {
+ const instance = homeInstance();
+ await signIn(page, 'owner');
+ await resetHomes(page);
+ await connectHome(page, { label: 'Journey two' });
+ await openScene(page);
+
+ const light = await anyLight(instance);
+ const before = await readState(instance, light.entityId);
+ const wanted = before === 'on' ? 'off' : 'on';
+ const label = before === 'on' ? 'Turn off' : 'Turn on';
+
+ const button = page.getByRole('button', { name: new RegExp(`^${label} ${escapeRe(light.name)}\\b`) }).first();
+ await expect(button).toBeVisible({ timeout: 60_000 });
+ await button.click();
+
+ // Home Assistant's own answer. A button that flips its own label proves
+ // nothing about a bulb.
+ expect(await waitForState(instance, light.entityId, wanted, { timeout: 30_000 })).toBe(wanted);
+});
+
+test('journey 3: change a light in Home Assistant and see the house update', async ({ page }) => {
+ const instance = homeInstance();
+ await signIn(page, 'owner');
+ await openScene(page);
+
+ const light = await anyLight(instance);
+ const before = await readState(instance, light.entityId);
+ const wanted = before === 'on' ? 'off' : 'on';
+
+ // Nothing in the browser did this. The change arrives from the house, over
+ // the state stream, and the page has to follow it without being asked.
+ await fetch(`${instance.baseUrl}/api/services/light/turn_${wanted}`, {
+ method: 'POST',
+ headers: { authorization: `Bearer ${instance.token}`, 'content-type': 'application/json' },
+ body: JSON.stringify({ entity_id: light.entityId }),
+ });
+ await waitForState(instance, light.entityId, wanted, { timeout: 30_000 });
+
+ // The button offers the opposite action once the page knows the new state.
+ const nowOffers = wanted === 'on' ? 'Turn off' : 'Turn on';
+ await expect(
+ page.getByRole('button', { name: new RegExp(`^${nowOffers} ${escapeRe(light.name)}\\b`) }).first(),
+ ).toBeVisible({ timeout: 60_000 });
+});
+
+test('journey 8: the house goes away mid-session, and comes back, with no reload', async ({ page }) => {
+ const instance = homeInstance();
+ await signIn(page, 'owner');
+ await openScene(page);
+
+ const light = await anyLight(instance);
+ await expect(page.getByRole('button', { name: new RegExp(escapeRe(light.name)) }).first()).toBeVisible({ timeout: 60_000 });
+
+ // Stop Home Assistant under the running page. The page must say the state it
+ // is showing is stale rather than keep presenting it as live.
+ await stopHouse();
+ try {
+ await expect(page.locator('#hs-status')).toHaveAttribute('data-status', /stale|offline|reconnecting|error/, {
+ timeout: 120_000,
+ });
+ } finally {
+ await startHouse();
+ }
+
+ // And recover on its own, on the same page: no navigation, no reload.
+ await expect(page.locator('#hs-status')).toHaveAttribute('data-status', /live|connected|ok/, { timeout: 180_000 });
+ expect(page.url()).toContain('/smart-home/');
+});
+
+async function stopHouse() {
+ await runDocker(['stop', containerName()]);
+}
+
+async function startHouse() {
+ await runDocker(['start', containerName()]);
+ const instance = homeInstance();
+ // Wait for the house to answer again before handing control back, so the
+ // recovery assertion is about our reconnect and not about a boot still
+ // finishing.
+ const deadline = Date.now() + 180_000;
+ while (Date.now() < deadline) {
+ const res = await fetch(`${instance.baseUrl}/api/`, {
+ headers: { authorization: `Bearer ${instance.token}` },
+ signal: AbortSignal.timeout(4000),
+ }).catch(() => null);
+ if (res?.ok) return;
+ await new Promise((r) => setTimeout(r, 1000));
+ }
+ throw new Error('Home Assistant did not come back after being restarted');
+}
+
+/**
+ * The container this run's house lives in. Derived from the harness's naming so
+ * this can never stop a container belonging to another agent on this machine.
+ */
+function containerName() {
+ return `three-ws-home-test-${process.env.HOME_LIVE_NAME || 'e2e'}`;
+}
+
+async function runDocker(args) {
+ const { spawn } = await import('node:child_process');
+ await new Promise((resolve, reject) => {
+ const child = spawn('docker', args, { stdio: 'ignore' });
+ child.on('error', reject);
+ child.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`docker ${args.join(' ')} exited ${code}`))));
+ });
+}
+
+function escapeRe(text) {
+ return String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
diff --git a/tests/e2e/home-support.js b/tests/e2e/home-support.js
index faad71eff..a1a6f22fd 100644
--- a/tests/e2e/home-support.js
+++ b/tests/e2e/home-support.js
@@ -11,7 +11,6 @@
* catch, and only Home Assistant can tell us which happened.
*/
-import { randomBytes } from 'node:crypto';
import fs from 'node:fs';
import { expect } from '@playwright/test';
@@ -21,36 +20,62 @@ import { STACK_FILE } from './home-global-setup.js';
export { readState, readStates, waitForState };
-/** The house this run is driving, as global setup left it. */
-export function homeInstance() {
+/** The stack this run is driving, as global setup left it. */
+function stack() {
if (!fs.existsSync(STACK_FILE)) {
throw new Error('No home e2e stack: run through playwright.home.config.js, which sets it up.');
}
- return JSON.parse(fs.readFileSync(STACK_FILE, 'utf8')).home;
+ return JSON.parse(fs.readFileSync(STACK_FILE, 'utf8'));
+}
+
+/** The house this run is driving. */
+export function homeInstance() {
+ return stack().home;
+}
+
+/**
+ * Sign in as one of the two accounts global setup provisioned.
+ *
+ * Signing in rather than signing up on every journey is not a shortcut: account
+ * creation is rate limited to five per hour per IP, so a suite that registered
+ * per journey would pass once and then spend an hour reporting the rate limiter
+ * as a product failure. The accounts are real, made through the real signup
+ * page, and this is the real login endpoint.
+ *
+ * @param {import('@playwright/test').Page} page
+ * @param {'owner'|'guest'} role
+ */
+export async function signIn(page, role = 'owner') {
+ const account = stack().accounts[role];
+ if (!account) throw new Error(`no ${role} account in the e2e stack`);
+
+ const res = await page.request.post('/api/auth/login', {
+ data: { email: account.email, password: account.password },
+ headers: { 'content-type': 'application/json' },
+ timeout: 60_000,
+ });
+ if (!res.ok()) {
+ throw new Error(`login as ${role} returned ${res.status()}: ${(await res.text()).slice(0, 200)}`);
+ }
+ return account;
}
/**
- * A brand new three.ws account, registered through the real signup page, signed
- * in on this browser context.
+ * Take every home this account has off the platform.
*
- * A fresh account per journey is deliberate: these tests connect houses and
- * grant standing permissions on locks, and one journey's grant leaking into the
- * next would quietly disarm the gate the next one is trying to prove.
+ * 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.
*/
-export async function signUp(page, { prefix = 'home-e2e' } = {}) {
- const username = `${prefix}-${randomBytes(4).toString('hex')}`;
- const password = `Pw-${randomBytes(12).toString('base64url')}`;
-
- await page.goto('/register', { waitUntil: 'domcontentloaded' });
- await page.fill('#username', username);
- await page.fill('#password', password);
- await page.check('#tos-accept');
- await Promise.all([
- page.waitForURL((u) => !/\/register/.test(u.pathname), { timeout: 90_000 }),
- page.click('#submit'),
- ]);
-
- return { username, password, email: `${username}@users.three.ws.local` };
+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 : [];
+ for (const home of homes) {
+ await page.request.delete(`/api/home/${home.id}`, { timeout: 60_000 }).catch(() => {});
+ }
+ return homes.length;
}
/**
@@ -77,6 +102,32 @@ export async function connectHome(page, { label = 'The lane house' } = {}) {
return label;
}
+/**
+ * Open the connected house's 3D page, in the 2D view.
+ *
+ * The 2D view is the one with named buttons. It renders the same model, calls
+ * the same action endpoint and hits the same gate as the 3D view, so nothing
+ * about what is under test changes; what changes is that a click lands on
+ * "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');
+
+ await page.goto(`/smart-home/${homes[0].id}`, { waitUntil: 'domcontentloaded' });
+ const flat = page.locator('#hs-view-2d');
+ await expect(flat).toBeVisible({ timeout: 90_000 });
+ await flat.click();
+ await expect(flat).toHaveAttribute('aria-pressed', 'true', { timeout: 30_000 });
+
+ // Wait for the house to have been read, not for a spinner to stop: the room
+ // rail is only populated once the real registries have arrived.
+ await expect(page.locator('#hs-rooms')).not.toHaveAttribute('aria-busy', 'true', { timeout: 120_000 });
+ return homes[0].id;
+}
+
/**
* Every request the page makes, recorded. Journey 10 needs to prove a refusal
* cost no network call at all, which is a claim about what did NOT happen.