@junobuild/emulator-playwright 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Dal Busco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# @junobuild/emulator-playwright
+
+A Playwright library to simplify the integration of the Juno Console and CLI in E2E tests.
+
+## Page Objects
+
+- **ConsolePage** — Interact with the Juno Console (sign in, create satellites, copy IDs, etc.)
+- **CliPage** — Wrap the Juno CLI (login, deploy, snapshots, config management, etc.)
+- **SatellitePage** — Interact with a deployed satellite project
+
+## Test Suite Helpers
+
+### `initEmulatorSuite`
+
+Creates a full emulator test suite: signs in to the Console, creates a satellite, and logs in via the CLI.
+
+```ts
+const getPages = initEmulatorSuite({satelliteKind: 'website'});
+
+test('...', async () => {
+  const {consolePage, cliPage} = getPages();
+});
+```
+
+### `initSatelliteSuite`
+
+Lighter suite for tests that target an already-deployed satellite from the local config.
+
+```ts
+const getPages = initSatelliteSuite();
+
+test('...', async () => {
+  const {satelliteId, cliPage} = getPages();
+});
+```
+
+## Requirements
+
+- Juno emulator running locally
+- `juno.config.ts` with a `<DEV_SATELLITE_ID>` placeholder

package/dist/index.js

@@ -0,0 +1,2 @@
+var a={auth:{signInDev:"btn-sign-in-dev",switchDevAccount:"btn-switch-account-dev",inputDevIdentifier:"input-dev-identifier",continueDevAccount:"btn-continue-dev"},launchpad:{launch:"btn-launch-first-satellite",launchExtraSatellite:"btn-launch-extra-satellite",actions:"btn-open-actions"},createSatellite:{create:"btn-create-satellite",input:"input-satellite-name",website:"input-radio-satellite-website",application:"input-radio-satellite-application",continue:"btn-continue-overview"},satelliteOverview:{visit:"link-visit-satellite",copySatelliteId:"btn-copy-satellite-id"},navbar:{openWallet:"btn-open-wallet",getIcp:"btn-get-icp",getCycles:"btn-get-cycles"},createAnalytics:{navLink:"link-analytics-dashboard",launch:"btn-launch-analytics",create:"btn-create-analytics",close:"btn-close-analytics-wizard"},wizard:{closeInsufficientFunds:"btn-close-insufficient-funds"}};import{test as b}from"@playwright/test";import{assertNonNullish as A,notEmptyString as O}from"@dfinity/utils";import{execute as l,spawn as I}from"@junobuild/cli-tools";import{statSync as k}from"node:fs";import{readdir as _,readFile as T,writeFile as B}from"node:fs/promises";import{join as f}from"node:path";var C={command:"juno",args:[]},E=["--mode","development","--headless"],m=class{command;commandArgs;constructor({command:t}){let{command:e,args:o}=t??C;this.command=e,this.commandArgs=o}buildArgs(t){return[...this.commandArgs,...t,...E]}};var u=f(process.cwd(),"juno.config.ts"),p=class n extends m{#t;constructor({satelliteId:t,command:e}){super({command:e}),this.#t=t}static initWithoutLogin(t){return new n(t)}static async initWithEmulatorLogin(t){let e=new n(t);return await e.initConfig(),await e.loginWithEmulator(),await e.applyConfig(),e}async initConfig(){let t=await T(u,"utf-8");t=t.replace("<DEV_SATELLITE_ID>",this.#t),await B(u,t,"utf-8")}async revertConfig(){let t=await T(u,"utf-8");t=t.replace(this.#t,"<DEV_SATELLITE_ID>"),await B(u,t,"utf-8")}async toggleSatelliteId({satelliteId:t}){await this.revertConfig(),this.#t=t,await this.initConfig()}async loginWithEmulator(){await l({command:this.command,args:this.buildArgs(["login","--emulator"])})}async applyConfig(){await l({command:this.command,args:this.buildArgs(["config","apply","--force"])})}async logout(){await l({command:this.command,args:this.buildArgs(["logout"])})}async clearHosting(){await l({command:this.command,args:this.buildArgs(["hosting","clear"])})}async deployHosting({clear:t}){await l({command:this.command,args:this.buildArgs(["hosting","deploy",...t?["--clear"]:[]])})}async createSnapshot({target:t}){await l({command:this.command,args:this.buildArgs(["snapshot","create","--target",t])})}async restoreSnapshot({target:t}){await l({command:this.command,args:this.buildArgs(["snapshot","restore","--target",t])})}async deleteSnapshot({target:t}){await l({command:this.command,args:this.buildArgs(["snapshot","delete","--target",t])})}async downloadSnapshot({target:t}){return await l({command:this.command,args:this.buildArgs(["snapshot","download","--target",t])}),await this.getSnapshotFsFolder()}async getSnapshotFsFolder(){let t=f(process.cwd(),".snapshots"),e=await _(t,{withFileTypes:!0}),[o]=e.filter(i=>i.isDirectory()).map(({name:i})=>{let r=f(t,i),{birthtimeMs:c}=k(r);return{path:r,time:c}}).sort((i,r)=>r.time-i.time);return A(o),{snapshotFolder:o.path}}async uploadSnapshot({target:t,folder:e}){await l({command:this.command,args:this.buildArgs(["snapshot","upload","--target",t,"--dir",e])})}async listSnapshot({target:t}){let e="";await I({command:this.command,args:this.buildArgs(["snapshot","list","--target",t]),stdout:r=>e+=r,silentErrors:!0});let[o,i]=e.split("Snapshot found:");return{snapshotId:O(i)?i.trim():void 0}}async whoami(){let t="";await I({command:this.command,args:this.buildArgs(["whoami"]),stdout:y=>t+=y,silentErrors:!0});let[e,o,i,r]=t.split(" "),[c]=r.split(`
+`);return{accessKey:c.replace("\x1B[32m","").replace("\x1B[39m","").trim()}}async close({cleanUp:t}={cleanUp:!0}){t&&await this.cleanUp(),await this.logout()}async cleanUp(){await this.revertConfig()}};import{notEmptyString as F}from"@dfinity/utils";import{PrincipalTextSchema as U}from"@dfinity/zod-schemas";import{expect as s}from"@playwright/test";var P={timeout:15e3},g={timeout:2*15e3},Q={timeout:4*15e3};var d=class{page;context;browser;constructor({page:t,context:e,browser:o}){this.page=t,this.context=e,this.browser=o}async close(){await this.page.close()}};import{expect as x}from"@playwright/test";var h=class extends d{async reload({title:t}={title:"Juno / Satellite"}){await x.poll(async()=>(await this.page.reload({waitUntil:"load"}),await this.page.title()),{...g,intervals:[1e3,2e3,1e4]}).toBe(t)}async assertScreenshot(){await x(this.page).toHaveScreenshot({fullPage:!0})}};var w=class n extends d{constructor(t){super(t)}static async initWithSignIn(t){let e=new n(t);return await e.goto(),await e.signIn(),e}async goto({path:t}={path:"/"}){await this.page.goto(t)}async signIn(){await s(this.page.getByTestId(a.auth.switchDevAccount)).toBeVisible(g),await this.page.getByTestId(a.auth.switchDevAccount).click(),await s(this.page.getByTestId(a.auth.inputDevIdentifier)).toBeVisible(),await this.page.getByTestId(a.auth.inputDevIdentifier).fill(crypto.randomUUID().replaceAll("-","")),await s(this.page.getByTestId(a.auth.continueDevAccount)).toBeVisible(),await this.page.getByTestId(a.auth.continueDevAccount).click()}async createSatellite(t){await s(this.page.getByTestId(a.launchpad.launch)).toBeVisible(g),await this.page.getByTestId(a.launchpad.launch).click(),await this.createSatelliteWizard(t)}async openCreateAdditionalSatelliteWizard(t){await s(this.page.getByTestId(a.launchpad.actions)).toBeVisible(g),await this.page.getByTestId(a.launchpad.actions).click(),await s(this.page.getByTestId(a.launchpad.launchExtraSatellite)).toBeVisible(g),await this.page.getByTestId(a.launchpad.launchExtraSatellite).click(),await this.createSatelliteWizard(t)}async createSatelliteWizard({kind:t}){await s(this.page.getByTestId(a.createSatellite.create)).toBeVisible({timeout:15e3}),await this.page.getByTestId(a.createSatellite.input).fill("Test"),await this.page.getByTestId(a.createSatellite[t]).click(),await this.page.getByTestId(a.createSatellite.create).click(),await s(this.page.getByTestId(a.createSatellite.continue)).toBeVisible(g),await this.page.getByTestId(a.createSatellite.continue).click()}async visitSatelliteSite({title:t}={title:"Juno / Satellite"}){await s(this.page.getByTestId(a.satelliteOverview.visit)).toBeVisible(g);let e=this.context.waitForEvent("page");await this.page.getByTestId(a.satelliteOverview.visit).click();let o=await e;return await s(o).toHaveTitle(t),new h({page:o,browser:this.browser,context:this.context})}async getCycles(){await s(this.page.getByTestId(a.navbar.openWallet)).toBeVisible(),await this.page.getByTestId(a.navbar.openWallet).click(),await s(this.page.getByTestId(a.navbar.getCycles)).toBeVisible(),await this.page.getByTestId(a.navbar.getCycles).click(),await s(this.page.getByText("330.010 TCycles")).toBeVisible({timeout:65e3})}async copySatelliteID(){await s(this.page.getByTestId(a.satelliteOverview.copySatelliteId)).toBeVisible(),await this.page.getByTestId(a.satelliteOverview.copySatelliteId).click();let t=await this.page.evaluate(()=>navigator.clipboard.readText());return s(F(t)).toBeTruthy(),s(U.safeParse(t).success).toBeTruthy(),t}async addSatelliteAdminAccessKey({satelliteId:t,accessKey:e}){await this.goto({path:`/satellite/?s=${t}&tab=setup`});let o=this.page.locator("button",{hasText:"Add an access key"});await s(o).toBeVisible(P),await o.click();let i=this.page.locator("form");await i.getByRole("radio",{name:/enter one manually/i}).check();let r=i.getByLabel("Access Key ID");await s(r).toBeEnabled(),await r.fill(e),await i.locator('select[name="scope"]').selectOption("admin");let c=i.getByRole("button",{name:/^submit$/i});await s(c).toBeEnabled(),await c.click(),await s(this.page.getByText("Access Key Added")).toBeVisible(P)}};var ut=({satelliteKind:n,cli:t})=>{let e,o;return b.beforeAll(async({playwright:i})=>{b.setTimeout(12e4);let r=await i.chromium.launch(),c=await r.newContext(),v=await c.newPage();e=await w.initWithSignIn({page:v,context:c,browser:r}),await e.createSatellite({kind:n});let y=await e.copySatelliteID();o=await p.initWithEmulatorLogin({satelliteId:y,...t})}),b.afterAll(async()=>{let i=await Promise.allSettled([e.close(),o.close()]);if(i.find(({status:r})=>r==="rejected"))throw console.error(i),new Error("Failed to close test suite!")}),()=>({consolePage:e,cliPage:o})};import{assertNonNullish as W}from"@dfinity/utils";import{test as N}from"@playwright/test";import{readJunoConfig as V}from"@junobuild/config-loader";var D="juno.config",J={filename:D},L=async n=>await V({...J,config:e=>typeof e=="function"?e(n):e}),S=async n=>{try{return{ok:await L(n)}}catch(t){return{err:t}}};var It=()=>{let n,t;return N.beforeAll(async()=>{let e=await S({mode:"development"});if("err"in e)throw new Error("Failed to read config");let{ok:o}=e,i=o.satellite.ids?.development;W(i),n=i,t=await p.initWithoutLogin({satelliteId:n})}),()=>({satelliteId:n,cliPage:t})};export{p as CliPage,w as ConsolePage,h as SatellitePage,ut as initEmulatorSuite,It as initSatelliteSuite,a as testIds};

package/dist/types/constants/e2e.constants.d.ts

@@ -0,0 +1,9 @@
+export declare const TIMEOUT_SHORT: {
+    timeout: number;
+};
+export declare const TIMEOUT_AVERAGE: {
+    timeout: number;
+};
+export declare const TIMEOUT_LONG: {
+    timeout: number;
+};

package/dist/types/constants/test-ids.constants.d.ts

@@ -0,0 +1,38 @@
+export declare const testIds: {
+    readonly auth: {
+        readonly signInDev: "btn-sign-in-dev";
+        readonly switchDevAccount: "btn-switch-account-dev";
+        readonly inputDevIdentifier: "input-dev-identifier";
+        readonly continueDevAccount: "btn-continue-dev";
+    };
+    readonly launchpad: {
+        readonly launch: "btn-launch-first-satellite";
+        readonly launchExtraSatellite: "btn-launch-extra-satellite";
+        readonly actions: "btn-open-actions";
+    };
+    readonly createSatellite: {
+        readonly create: "btn-create-satellite";
+        readonly input: "input-satellite-name";
+        readonly website: "input-radio-satellite-website";
+        readonly application: "input-radio-satellite-application";
+        readonly continue: "btn-continue-overview";
+    };
+    readonly satelliteOverview: {
+        readonly visit: "link-visit-satellite";
+        readonly copySatelliteId: "btn-copy-satellite-id";
+    };
+    readonly navbar: {
+        readonly openWallet: "btn-open-wallet";
+        readonly getIcp: "btn-get-icp";
+        readonly getCycles: "btn-get-cycles";
+    };
+    readonly createAnalytics: {
+        readonly navLink: "link-analytics-dashboard";
+        readonly launch: "btn-launch-analytics";
+        readonly create: "btn-create-analytics";
+        readonly close: "btn-close-analytics-wizard";
+    };
+    readonly wizard: {
+        readonly closeInsufficientFunds: "btn-close-insufficient-funds";
+    };
+};

package/dist/types/index.d.ts

@@ -0,0 +1,7 @@
+export * from './constants/test-ids.constants';
+export * from './init.emulator';
+export * from './init.satellite';
+export * from './page-objects/cli.page';
+export * from './page-objects/console.page';
+export * from './page-objects/satellite.page';
+export type * from './types/test-id';

package/dist/types/init.emulator.d.ts

@@ -0,0 +1,12 @@
+import type { CliContextPageParams } from './page-objects/_cli-context.page';
+import { CliPage } from './page-objects/cli.page';
+import { ConsolePage } from './page-objects/console.page';
+interface EmulatorSuitePages {
+    consolePage: ConsolePage;
+    cliPage: CliPage;
+}
+export declare const initEmulatorSuite: ({ satelliteKind, cli }: {
+    satelliteKind: "website" | "application";
+    cli?: CliContextPageParams;
+}) => (() => EmulatorSuitePages);
+export {};

package/dist/types/init.satellite.d.ts

@@ -0,0 +1,7 @@
+import { CliPage } from './page-objects/cli.page';
+interface SatellitePages {
+    satelliteId: string;
+    cliPage: CliPage;
+}
+export declare const initSatelliteSuite: () => (() => SatellitePages);
+export {};

package/dist/types/page-objects/_browser.page.d.ts

@@ -0,0 +1,13 @@
+import type { Browser, BrowserContext, Page } from '@playwright/test';
+export interface BrowserPageParams {
+    page: Page;
+    context: BrowserContext;
+    browser: Browser;
+}
+export declare abstract class BrowserPage {
+    protected readonly page: Page;
+    protected readonly context: BrowserContext;
+    protected readonly browser: Browser;
+    protected constructor({ page, context, browser }: BrowserPageParams);
+    close(): Promise<void>;
+}

package/dist/types/page-objects/_cli-context.page.d.ts

@@ -0,0 +1,12 @@
+export interface CliContextPageParams {
+    command?: {
+        command: string;
+        args: string[];
+    };
+}
+export declare abstract class CliContextPage {
+    protected readonly command: string;
+    protected readonly commandArgs: string[];
+    protected constructor({ command }: CliContextPageParams);
+    protected buildArgs(args: string[]): string[];
+}

package/dist/types/page-objects/cli.page.d.ts

@@ -0,0 +1,56 @@
+import type { PrincipalText } from '@dfinity/zod-schemas';
+import { type CliContextPageParams, CliContextPage } from './_cli-context.page';
+export interface CliPageParams extends CliContextPageParams {
+    satelliteId: PrincipalText;
+}
+export declare class CliPage extends CliContextPage {
+    #private;
+    private constructor();
+    static initWithoutLogin(params: CliPageParams): CliPage;
+    static initWithEmulatorLogin(params: CliPageParams): Promise<CliPage>;
+    protected initConfig(): Promise<void>;
+    private revertConfig;
+    toggleSatelliteId({ satelliteId }: {
+        satelliteId: PrincipalText;
+    }): Promise<void>;
+    protected loginWithEmulator(): Promise<void>;
+    applyConfig(): Promise<void>;
+    private logout;
+    clearHosting(): Promise<void>;
+    deployHosting({ clear }: {
+        clear: boolean;
+    }): Promise<void>;
+    createSnapshot({ target }: {
+        target: 'satellite' | 'orbiter' | 'mission-control';
+    }): Promise<void>;
+    restoreSnapshot({ target }: {
+        target: 'satellite' | 'orbiter' | 'mission-control';
+    }): Promise<void>;
+    deleteSnapshot({ target }: {
+        target: 'satellite' | 'orbiter' | 'mission-control';
+    }): Promise<void>;
+    downloadSnapshot({ target }: {
+        target: 'satellite' | 'orbiter' | 'mission-control';
+    }): Promise<{
+        snapshotFolder: string;
+    }>;
+    getSnapshotFsFolder(): Promise<{
+        snapshotFolder: string;
+    }>;
+    uploadSnapshot({ target, folder }: {
+        target: 'satellite' | 'orbiter' | 'mission-control';
+        folder: string;
+    }): Promise<void>;
+    listSnapshot({ target }: {
+        target: 'satellite' | 'orbiter' | 'mission-control';
+    }): Promise<{
+        snapshotId: string | undefined;
+    }>;
+    whoami(): Promise<{
+        accessKey: string;
+    }>;
+    close({ cleanUp }?: {
+        cleanUp: boolean;
+    }): Promise<void>;
+    cleanUp(): Promise<void>;
+}

package/dist/types/page-objects/console.page.d.ts

@@ -0,0 +1,27 @@
+import { type PrincipalText } from '@dfinity/zod-schemas';
+import { BrowserPage, type BrowserPageParams } from './_browser.page';
+import { SatellitePage } from './satellite.page';
+export declare class ConsolePage extends BrowserPage {
+    private constructor();
+    static initWithSignIn(params: BrowserPageParams): Promise<ConsolePage>;
+    goto({ path }?: {
+        path: string;
+    }): Promise<void>;
+    private signIn;
+    createSatellite(params: {
+        kind: 'website' | 'application';
+    }): Promise<void>;
+    openCreateAdditionalSatelliteWizard(params: {
+        kind: 'website' | 'application';
+    }): Promise<void>;
+    private createSatelliteWizard;
+    visitSatelliteSite({ title }?: {
+        title: string;
+    }): Promise<SatellitePage>;
+    getCycles(): Promise<void>;
+    copySatelliteID(): Promise<string>;
+    addSatelliteAdminAccessKey({ satelliteId, accessKey }: {
+        satelliteId: PrincipalText;
+        accessKey: string;
+    }): Promise<void>;
+}

package/dist/types/page-objects/satellite.page.d.ts

@@ -0,0 +1,7 @@
+import { BrowserPage } from './_browser.page';
+export declare class SatellitePage extends BrowserPage {
+    reload({ title }?: {
+        title: string;
+    }): Promise<void>;
+    assertScreenshot(): Promise<void>;
+}

package/dist/types/types/test-id.d.ts

@@ -0,0 +1,6 @@
+type TestCTAType = 'btn' | 'link' | 'input';
+type TestAction = string;
+export type TestId = `${TestCTAType}-${TestAction}`;
+type TestSuite = string;
+export type TestIds = Record<TestSuite, Record<string, TestId>>;
+export {};

package/dist/types/utils/config.utils.d.ts

@@ -0,0 +1,6 @@
+import type { JunoConfig, JunoConfigEnv } from '@junobuild/config';
+export declare const readConfig: (env: JunoConfigEnv) => Promise<{
+    ok: JunoConfig;
+} | {
+    err: unknown;
+}>;

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@junobuild/emulator-playwright",
+  "version": "0.0.1",
+  "description": "A Playwright library to simplify the integration of the Juno Console and CLI in E2E tests.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/junobuild/emulator-playwright.git"
+  },
+  "bugs": {
+    "url": "https://github.com/junobuild/emulator-playwright"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "playwright",
+    "e2e",
+    "test"
+  ],
+  "homepage": "https://github.com/junobuild/emulator-playwright#readme",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "format": "prettier . --write",
+    "format:check": "prettier --check .",
+    "ts-declaration": "tsc --emitDeclarationOnly --outDir dist/types",
+    "build": "tsc --noEmit && node rmdir.mjs && node esbuild.mjs && npm run ts-declaration",
+    "lint": "eslint --max-warnings 0"
+  },
+  "devDependencies": {
+    "@dfinity/eslint-config-oisy-wallet": "^0.2.3",
+    "@types/node": "^25.3.0",
+    "esbuild": "^0.27.3",
+    "prettier": "^3.8.1",
+    "prettier-plugin-organize-imports": "^4.3.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=24",
+    "npm": ">=11.5.1 <12.0.0"
+  },
+  "peerDependencies": {
+    "@dfinity/utils": "^4.1.0",
+    "@dfinity/zod-schemas": "^3.0.2",
+    "@junobuild/cli-tools": "^0.10.2",
+    "@junobuild/config-loader": "^0.4.8",
+    "@playwright/test": "^1.52.0"
+  }
+}