@simplysf/simply-utam-core 0.0.0

package/README.md

@@ -0,0 +1,114 @@
+# @simplysf/simply-utam-core
+
+[![NPM](https://img.shields.io/npm/v/@simplysf/simply-utam-core?label=@simplysf/simply-utam-core)](https://npmjs.com/@simplysf/simply-utam-core) [![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://raw.githubusercontent.com/SimplySF/simply-utam/main/LICENSE.txt)
+
+Org authentication, Lightning navigation, and debugging helpers for
+[UTAM](https://utam.dev/) UI tests against Salesforce, built by [SimplySF](https://github.com/SimplySF).
+
+It logs the test browser in to an org you have already authorized with the Salesforce CLI — no
+passwords in the test project — and opens Lightning pages directly, so a test starts on the page it
+is about instead of clicking its way there.
+
+## Install
+
+```bash
+npm install --save-dev @simplysf/simply-utam-core
+```
+
+Requires Node.js 22 or later, and an org authorized with `sf org login web` (or any other `sf org
+login` flow) on the machine running the tests.
+
+## Usage
+
+Point `UTAM_USERNAME` at the org's username or alias, then navigate from a WebdriverIO spec:
+
+```ts
+import { LightningNavigator, logUtamHtml } from '@simplysf/simply-utam-core';
+import AccountDetail from '../pageObjects/accountDetail'; // your compiled UTAM page object
+
+const navigator = new LightningNavigator();
+
+describe('Account record', () => {
+  it('opens on the detail page', async () => {
+    await navigator.goToRecord('MyApp', '001000000000001AAA');
+
+    const accountDetail = await utam.load(AccountDetail);
+    await logUtamHtml(accountDetail); // prints the selector and rendered HTML when a locator misbehaves
+  });
+});
+```
+
+`LightningNavigator` uses WebdriverIO's global `browser` by default and a `TestEnvironment` for
+`UTAM_USERNAME`; pass either explicitly to override:
+
+```ts
+const navigator = new LightningNavigator({
+  environment: new TestEnvironment({ username: 'qa-sandbox' }),
+  browser,
+});
+```
+
+App names are developer names. A bare name is treated as a custom app in the default namespace
+(`MyApp` opens `c__MyApp`); a namespaced name such as `standard__Sales` is used as given.
+
+### How login works
+
+`TestEnvironment` loads the org from the Salesforce CLI's auth store with `@salesforce/core` and asks
+Salesforce's [single-access endpoint](https://help.salesforce.com/s/articleView?id=xcloud.frontdoor_singleaccess.htm&type=5)
+for a one-time frontdoor URL. The access token never appears in a URL, so it does not end up in
+browser history, WebDriver logs, or a screenshot of the address bar. The org is authenticated once per
+`TestEnvironment` and shared by every navigation.
+
+## API
+
+Everything below is exported from the package root and is semver-covered. Anything not listed is
+internal.
+
+### Org authentication
+
+| Export                                          | Description                                                                                                               |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `TestEnvironment`                               | The org under test. `new TestEnvironment({ username?, env? })` throws when neither a username nor `UTAM_USERNAME` is set. |
+| `testEnvironment.getOrg()`                      | The authenticated `Org`. Authenticates on first call and shares the result; a failure is not cached.                      |
+| `testEnvironment.init()`                        | Authenticates eagerly, for a runner hook that wants auth failures reported before any test starts. Optional.              |
+| `testEnvironment.buildFrontdoorUrl(returnUrl?)` | A one-time URL that logs a browser in and lands on `returnUrl`.                                                           |
+| `USERNAME_ENV`                                  | `'UTAM_USERNAME'`.                                                                                                        |
+| `TestEnvironmentOptions`, `EnvLike`             | Types for the constructor options and an environment-shaped map.                                                          |
+
+### Navigation
+
+| Export                                                                | Description                                                                                       |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `LightningNavigator`                                                  | `new LightningNavigator({ environment?, browser? })`; every method logs in and opens a page.      |
+| `navigator.goToLoginUrl(returnUrl?)`                                  | Log in and open any path, or the org's default landing page.                                      |
+| `navigator.goToApplication(app)`                                      | An app's home page.                                                                               |
+| `navigator.goToCreateNewRecord(app, objectApiName)`                   | An object's new-record form.                                                                      |
+| `navigator.goToRecord(app, recordId)`                                 | A record's detail page.                                                                           |
+| `navigator.goToRelatedList(app, recordId, relatedListName)`           | One of a record's related lists.                                                                  |
+| `applicationPath`, `newRecordPath`, `recordPath`, `relatedListPath`   | The Lightning paths the methods above open, for a caller building its own URLs.                   |
+| `lightningAppName(app)`                                               | The namespacing rule: `MyApp` becomes `c__MyApp`, a namespaced name is unchanged.                 |
+| `NavigableBrowser`, `FrontdoorUrlSource`, `LightningNavigatorOptions` | Structural types: anything with `navigateTo(url)`, anything with `buildFrontdoorUrl(returnUrl?)`. |
+
+### Debugging
+
+| Export                          | Description                                                                           |
+| ------------------------------- | ------------------------------------------------------------------------------------- |
+| `logUtamHtml(utamObject, log?)` | Logs the selector a UTAM object resolved through and its HTML, shadow roots included. |
+| `getUtamHtml(utamObject)`       | The same `{ selector, html }` without logging it, e.g. to attach to a test report.    |
+| `formatUtamHtml(utamHtml)`      | The colored block `logUtamHtml` writes.                                               |
+| `UtamElementLike`, `UtamHtml`   | Types: any UTAM page object or element, and what it resolved to.                      |
+
+WebdriverIO and UTAM are not dependencies: the browser and UTAM objects are typed structurally, so
+the package works with whichever versions your test project already uses.
+
+## Issues
+
+Please report any issues at https://github.com/SimplySF/simply-utam/issues
+
+## Contributing
+
+This package is part of the [`simply-utam`](https://github.com/SimplySF/simply-utam) monorepo. See [CONTRIBUTING.md](CONTRIBUTING.md) for what's specific to this package, and the repo's [root CONTRIBUTING.md](https://github.com/SimplySF/simply-utam/blob/main/CONTRIBUTING.md) for repo structure, setup, commit conventions, and how to submit a pull request. Please also read our [Code of Conduct](https://github.com/SimplySF/simply-utam/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+Licensed under the [Apache-2.0](https://raw.githubusercontent.com/SimplySF/simply-utam/main/LICENSE.txt) license.

package/lib/index.d.ts

@@ -0,0 +1,4 @@
+export { TestEnvironment, USERNAME_ENV, type EnvLike, type TestEnvironmentOptions } from './test-environment.js';
+export { applicationPath, lightningAppName, newRecordPath, recordPath, relatedListPath } from './lightning-paths.js';
+export { LightningNavigator, type FrontdoorUrlSource, type LightningNavigatorOptions, type NavigableBrowser, } from './navigator.js';
+export { formatUtamHtml, getUtamHtml, logUtamHtml, type UtamElementLike, type UtamHtml } from './utam-html.js';

package/lib/index.js

@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+// Everything exported from this file is this package's public API and is semver-covered: adding
+// an export is a minor/patch change, but removing or renaming one is breaking.
+// `test/index.test.ts` pins the exported-key list so an accidental removal fails a test instead
+// of silently shipping in a patch release.
+//
+// Nothing here depends on WebdriverIO or UTAM at runtime: the browser and UTAM objects are typed
+// structurally, so consumers bring whichever versions their test project already uses.
+export { TestEnvironment, USERNAME_ENV } from './test-environment.js';
+export { applicationPath, lightningAppName, newRecordPath, recordPath, relatedListPath } from './lightning-paths.js';
+export { LightningNavigator, } from './navigator.js';
+export { formatUtamHtml, getUtamHtml, logUtamHtml } from './utam-html.js';
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,gGAAgG;AAChG,+EAA+E;AAC/E,gGAAgG;AAChG,2CAA2C;AAC3C,EAAE;AACF,iGAAiG;AACjG,uFAAuF;AAEvF,OAAO,EAAE,eAAe,EAAE,YAAY,EAA6C,MAAM,uBAAuB,CAAC;AACjH,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACrH,OAAO,EACL,kBAAkB,GAInB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,EAAuC,MAAM,gBAAgB,CAAC"}

package/lib/lightning-paths.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The app segment of a Lightning URL. A bare developer name is a custom app in the default
+ * namespace (`MyApp` becomes `c__MyApp`); a name that already carries a namespace
+ * (`standard__Sales`, `acme__Billing`) is used as given.
+ *
+ * @param applicationName The app's developer name, with or without a namespace prefix.
+ */
+export declare function lightningAppName(applicationName: string): string;
+/**
+ * The home page of a Lightning app.
+ *
+ * @param applicationName The app's developer name.
+ */
+export declare function applicationPath(applicationName: string): string;
+/**
+ * The new-record form for an object, opened inside a Lightning app.
+ *
+ * @param applicationName The app's developer name.
+ * @param objectApiName The object's API name, e.g. `Account` or `Invoice__c`.
+ */
+export declare function newRecordPath(applicationName: string, objectApiName: string): string;
+/**
+ * A record's detail page, opened inside a Lightning app.
+ *
+ * @param applicationName The app's developer name.
+ * @param recordId The record's 15- or 18-character id.
+ */
+export declare function recordPath(applicationName: string, recordId: string): string;
+/**
+ * One of a record's related lists, opened inside a Lightning app.
+ *
+ * @param applicationName The app's developer name.
+ * @param recordId The parent record's id.
+ * @param relatedListName The relationship name, e.g. `Contacts` or `Invoice_Lines__r`.
+ */
+export declare function relatedListPath(applicationName: string, recordId: string, relatedListName: string): string;

package/lib/lightning-paths.js

@@ -0,0 +1,67 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+// Lightning Experience paths, relative to the org's instance URL. Each is what a frontdoor URL's
+// return path points at; `LightningNavigator` pairs them with a login.
+/**
+ * The app segment of a Lightning URL. A bare developer name is a custom app in the default
+ * namespace (`MyApp` becomes `c__MyApp`); a name that already carries a namespace
+ * (`standard__Sales`, `acme__Billing`) is used as given.
+ *
+ * @param applicationName The app's developer name, with or without a namespace prefix.
+ */
+export function lightningAppName(applicationName) {
+    return applicationName.includes('__') ? applicationName : `c__${applicationName}`;
+}
+/**
+ * The home page of a Lightning app.
+ *
+ * @param applicationName The app's developer name.
+ */
+export function applicationPath(applicationName) {
+    return `${appBase(applicationName)}/page/home`;
+}
+/**
+ * The new-record form for an object, opened inside a Lightning app.
+ *
+ * @param applicationName The app's developer name.
+ * @param objectApiName The object's API name, e.g. `Account` or `Invoice__c`.
+ */
+export function newRecordPath(applicationName, objectApiName) {
+    return `${appBase(applicationName)}/o/${encodeURIComponent(objectApiName)}/new`;
+}
+/**
+ * A record's detail page, opened inside a Lightning app.
+ *
+ * @param applicationName The app's developer name.
+ * @param recordId The record's 15- or 18-character id.
+ */
+export function recordPath(applicationName, recordId) {
+    return `${appBase(applicationName)}/r/${encodeURIComponent(recordId)}/view`;
+}
+/**
+ * One of a record's related lists, opened inside a Lightning app.
+ *
+ * @param applicationName The app's developer name.
+ * @param recordId The parent record's id.
+ * @param relatedListName The relationship name, e.g. `Contacts` or `Invoice_Lines__r`.
+ */
+export function relatedListPath(applicationName, recordId, relatedListName) {
+    return `${appBase(applicationName)}/r/${encodeURIComponent(recordId)}/related/${encodeURIComponent(relatedListName)}/view`;
+}
+function appBase(applicationName) {
+    return `/lightning/app/${encodeURIComponent(lightningAppName(applicationName))}`;
+}
+//# sourceMappingURL=lightning-paths.js.map

package/lib/lightning-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lightning-paths.js","sourceRoot":"","sources":["../src/lightning-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,iGAAiG;AACjG,uEAAuE;AAEvE;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,eAAuB;IACtD,OAAO,eAAe,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,MAAM,eAAe,EAAE,CAAC;AACpF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,eAAuB;IACrD,OAAO,GAAG,OAAO,CAAC,eAAe,CAAC,YAAY,CAAC;AACjD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,eAAuB,EAAE,aAAqB;IAC1E,OAAO,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,kBAAkB,CAAC,aAAa,CAAC,MAAM,CAAC;AAClF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,eAAuB,EAAE,QAAgB;IAClE,OAAO,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,kBAAkB,CAAC,QAAQ,CAAC,OAAO,CAAC;AAC9E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,eAAuB,EAAE,QAAgB,EAAE,eAAuB;IAChG,OAAO,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,kBAAkB,CAAC,QAAQ,CAAC,YAAY,kBAAkB,CAAC,eAAe,CAAC,OAAO,CAAC;AAC7H,CAAC;AAED,SAAS,OAAO,CAAC,eAAuB;IACtC,OAAO,kBAAkB,kBAAkB,CAAC,gBAAgB,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC;AACnF,CAAC"}

package/lib/navigator.d.ts

@@ -0,0 +1,61 @@
+/** The part of a WebdriverIO browser the navigator drives. */
+export type NavigableBrowser = {
+    navigateTo(url: string): Promise<unknown>;
+};
+/** Anything that can mint a logged-in URL; `TestEnvironment` in practice. */
+export type FrontdoorUrlSource = {
+    buildFrontdoorUrl(returnUrl?: string): Promise<string>;
+};
+export type LightningNavigatorOptions = {
+    /** Where login URLs come from. Defaults to a `TestEnvironment` for `UTAM_USERNAME`. */
+    environment?: FrontdoorUrlSource;
+    /** The browser to drive. Defaults to WebdriverIO's global `browser`, looked up on each call. */
+    browser?: NavigableBrowser;
+};
+/**
+ * Logs the browser in to the test org and opens a Lightning page in one step. Every navigation
+ * goes through a fresh frontdoor URL, so each one also works as the first thing a test does.
+ */
+export declare class LightningNavigator {
+    #private;
+    /**
+     * Create a navigator.
+     *
+     * @param options The environment and browser to use; both have defaults.
+     */
+    constructor(options?: LightningNavigatorOptions);
+    /**
+     * Log in and open `returnUrl`, or the org's default landing page when it is omitted.
+     *
+     * @param returnUrl Path to open after login.
+     */
+    goToLoginUrl(returnUrl?: string): Promise<void>;
+    /**
+     * Log in and open a Lightning app's home page.
+     *
+     * @param applicationName The app's developer name; see `lightningAppName` for namespacing.
+     */
+    goToApplication(applicationName: string): Promise<void>;
+    /**
+     * Log in and open the new-record form for an object.
+     *
+     * @param applicationName The app's developer name.
+     * @param objectApiName The object's API name.
+     */
+    goToCreateNewRecord(applicationName: string, objectApiName: string): Promise<void>;
+    /**
+     * Log in and open a record's detail page.
+     *
+     * @param applicationName The app's developer name.
+     * @param recordId The record's id.
+     */
+    goToRecord(applicationName: string, recordId: string): Promise<void>;
+    /**
+     * Log in and open one of a record's related lists.
+     *
+     * @param applicationName The app's developer name.
+     * @param recordId The parent record's id.
+     * @param relatedListName The relationship name.
+     */
+    goToRelatedList(applicationName: string, recordId: string, relatedListName: string): Promise<void>;
+}

package/lib/navigator.js

@@ -0,0 +1,87 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { applicationPath, newRecordPath, recordPath, relatedListPath } from './lightning-paths.js';
+import { TestEnvironment } from './test-environment.js';
+/**
+ * Logs the browser in to the test org and opens a Lightning page in one step. Every navigation
+ * goes through a fresh frontdoor URL, so each one also works as the first thing a test does.
+ */
+export class LightningNavigator {
+    #environment;
+    #browser;
+    /**
+     * Create a navigator.
+     *
+     * @param options The environment and browser to use; both have defaults.
+     */
+    constructor(options = {}) {
+        this.#environment = options.environment ?? new TestEnvironment();
+        this.#browser = options.browser;
+    }
+    /**
+     * Log in and open `returnUrl`, or the org's default landing page when it is omitted.
+     *
+     * @param returnUrl Path to open after login.
+     */
+    async goToLoginUrl(returnUrl) {
+        const url = await this.#environment.buildFrontdoorUrl(returnUrl);
+        await this.#resolveBrowser().navigateTo(url);
+    }
+    /**
+     * Log in and open a Lightning app's home page.
+     *
+     * @param applicationName The app's developer name; see `lightningAppName` for namespacing.
+     */
+    async goToApplication(applicationName) {
+        await this.goToLoginUrl(applicationPath(applicationName));
+    }
+    /**
+     * Log in and open the new-record form for an object.
+     *
+     * @param applicationName The app's developer name.
+     * @param objectApiName The object's API name.
+     */
+    async goToCreateNewRecord(applicationName, objectApiName) {
+        await this.goToLoginUrl(newRecordPath(applicationName, objectApiName));
+    }
+    /**
+     * Log in and open a record's detail page.
+     *
+     * @param applicationName The app's developer name.
+     * @param recordId The record's id.
+     */
+    async goToRecord(applicationName, recordId) {
+        await this.goToLoginUrl(recordPath(applicationName, recordId));
+    }
+    /**
+     * Log in and open one of a record's related lists.
+     *
+     * @param applicationName The app's developer name.
+     * @param recordId The parent record's id.
+     * @param relatedListName The relationship name.
+     */
+    async goToRelatedList(applicationName, recordId, relatedListName) {
+        await this.goToLoginUrl(relatedListPath(applicationName, recordId, relatedListName));
+    }
+    #resolveBrowser() {
+        const browser = this.#browser ?? globalThis.browser;
+        if (!browser) {
+            throw new Error('No browser to navigate: pass one as the `browser` option, or run inside WebdriverIO so the global `browser` exists');
+        }
+        return browser;
+    }
+}
+//# sourceMappingURL=navigator.js.map

package/lib/navigator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigator.js","sourceRoot":"","sources":["../src/navigator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACnG,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAmBxD;;;GAGG;AACH,MAAM,OAAO,kBAAkB;IACpB,YAAY,CAAqB;IACjC,QAAQ,CAAoB;IAErC;;;;OAIG;IACH,YAAmB,UAAqC,EAAE;QACxD,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,WAAW,IAAI,IAAI,eAAe,EAAE,CAAC;QACjE,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAClC,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,YAAY,CAAC,SAAkB;QAC1C,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;QACjE,MAAM,IAAI,CAAC,eAAe,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IAC/C,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,eAAe,CAAC,eAAuB;QAClD,MAAM,IAAI,CAAC,YAAY,CAAC,eAAe,CAAC,eAAe,CAAC,CAAC,CAAC;IAC5D,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,mBAAmB,CAAC,eAAuB,EAAE,aAAqB;QAC7E,MAAM,IAAI,CAAC,YAAY,CAAC,aAAa,CAAC,eAAe,EAAE,aAAa,CAAC,CAAC,CAAC;IACzE,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,UAAU,CAAC,eAAuB,EAAE,QAAgB;QAC/D,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAC,CAAC;IACjE,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,eAAe,CAAC,eAAuB,EAAE,QAAgB,EAAE,eAAuB;QAC7F,MAAM,IAAI,CAAC,YAAY,CAAC,eAAe,CAAC,eAAe,EAAE,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC;IACvF,CAAC;IAED,eAAe;QACb,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,IAAK,UAA6C,CAAC,OAAO,CAAC;QACxF,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,oHAAoH,CACrH,CAAC;QACJ,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;CACF"}

package/lib/test-environment.d.ts

@@ -0,0 +1,43 @@
+import { Org } from '@salesforce/core';
+/** The environment variable naming the org a UTAM run authenticates to. */
+export declare const USERNAME_ENV = "UTAM_USERNAME";
+/** An environment-shaped map; `process.env` by default. */
+export type EnvLike = Record<string, string | undefined>;
+export type TestEnvironmentOptions = {
+    /** Username or alias of an org already authorized with the Salesforce CLI. Wins over `UTAM_USERNAME`. */
+    username?: string;
+    /** Where `UTAM_USERNAME` is read from. Defaults to `process.env`. */
+    env?: EnvLike;
+};
+/**
+ * The org a UTAM run tests against, resolved from the Salesforce CLI's local auth store.
+ */
+export declare class TestEnvironment {
+    #private;
+    readonly username: string;
+    /**
+     * Create a new environment for the given username, or `UTAM_USERNAME` when none is passed.
+     *
+     * @param options Explicit username and environment overrides.
+     */
+    constructor(options?: TestEnvironmentOptions);
+    /**
+     * Resolve the authenticated org. The first call authenticates and every later call shares its
+     * result, so callers need not coordinate who goes first; a failed attempt is not cached.
+     */
+    getOrg(): Promise<Org>;
+    /**
+     * Authenticate eagerly, for a runner hook that wants auth failures reported before any test
+     * starts. Optional: every other method authenticates on first use.
+     */
+    init(): Promise<void>;
+    /**
+     * Build a single-use frontdoor URL that logs the browser in and lands on `returnUrl`.
+     *
+     * The URL comes from Salesforce's single-access endpoint rather than a `sid=` query parameter,
+     * so the session's access token never appears in the browser's address bar or history.
+     *
+     * @param returnUrl Path to open after login, e.g. `/lightning/page/home`. Omit for the org's default landing page.
+     */
+    buildFrontdoorUrl(returnUrl?: string): Promise<string>;
+}

package/lib/test-environment.js

@@ -0,0 +1,68 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Org } from '@salesforce/core';
+/** The environment variable naming the org a UTAM run authenticates to. */
+export const USERNAME_ENV = 'UTAM_USERNAME';
+/**
+ * The org a UTAM run tests against, resolved from the Salesforce CLI's local auth store.
+ */
+export class TestEnvironment {
+    username;
+    #org;
+    /**
+     * Create a new environment for the given username, or `UTAM_USERNAME` when none is passed.
+     *
+     * @param options Explicit username and environment overrides.
+     */
+    constructor(options = {}) {
+        const username = options.username ?? (options.env ?? process.env)[USERNAME_ENV];
+        if (!username) {
+            throw new Error(`You must set a username using the ${USERNAME_ENV} env property for the test`);
+        }
+        this.username = username;
+    }
+    /**
+     * Resolve the authenticated org. The first call authenticates and every later call shares its
+     * result, so callers need not coordinate who goes first; a failed attempt is not cached.
+     */
+    async getOrg() {
+        this.#org ??= Org.create({ aliasOrUsername: this.username }).catch((error) => {
+            this.#org = undefined;
+            throw error;
+        });
+        return this.#org;
+    }
+    /**
+     * Authenticate eagerly, for a runner hook that wants auth failures reported before any test
+     * starts. Optional: every other method authenticates on first use.
+     */
+    async init() {
+        await this.getOrg();
+    }
+    /**
+     * Build a single-use frontdoor URL that logs the browser in and lands on `returnUrl`.
+     *
+     * The URL comes from Salesforce's single-access endpoint rather than a `sid=` query parameter,
+     * so the session's access token never appears in the browser's address bar or history.
+     *
+     * @param returnUrl Path to open after login, e.g. `/lightning/page/home`. Omit for the org's default landing page.
+     */
+    async buildFrontdoorUrl(returnUrl) {
+        const org = await this.getOrg();
+        return org.getFrontDoorUrl(returnUrl);
+    }
+}
+//# sourceMappingURL=test-environment.js.map

package/lib/test-environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-environment.js","sourceRoot":"","sources":["../src/test-environment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAC;AAEvC,2EAA2E;AAC3E,MAAM,CAAC,MAAM,YAAY,GAAG,eAAe,CAAC;AAY5C;;GAEG;AACH,MAAM,OAAO,eAAe;IACV,QAAQ,CAAS;IAEjC,IAAI,CAAgB;IAEpB;;;;OAIG;IACH,YAAmB,UAAkC,EAAE;QACrD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC;QAChF,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,qCAAqC,YAAY,4BAA4B,CAAC,CAAC;QACjG,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,MAAM;QACjB,IAAI,CAAC,IAAI,KAAK,GAAG,CAAC,MAAM,CAAC,EAAE,eAAe,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YACpF,IAAI,CAAC,IAAI,GAAG,SAAS,CAAC;YACtB,MAAM,KAAK,CAAC;QACd,CAAC,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,IAAI;QACf,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;IACtB,CAAC;IAED;;;;;;;OAOG;IACI,KAAK,CAAC,iBAAiB,CAAC,SAAkB;QAC/C,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;QAChC,OAAO,GAAG,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC;IACxC,CAAC;CACF"}

package/lib/utam-html.d.ts

@@ -0,0 +1,35 @@
+/** The part of a UTAM page object or element this module reads: its wrapped WebdriverIO element. */
+export type UtamElementLike = {
+    element: {
+        element: {
+            selector: unknown;
+            getHTML(options?: {
+                serializableShadowRoots?: boolean;
+            }): Promise<string>;
+        };
+    };
+};
+/** What a UTAM object resolved to in the page. */
+export type UtamHtml = {
+    selector: string;
+    html: string;
+};
+/**
+ * Read the selector a UTAM object resolved through and its rendered HTML, shadow roots included.
+ *
+ * @param utamObject A UTAM page object or element.
+ */
+export declare function getUtamHtml(utamObject: UtamElementLike): Promise<UtamHtml>;
+/**
+ * Render a `getUtamHtml` result as a colored block for a terminal.
+ *
+ * @param utamHtml The selector and HTML to render.
+ */
+export declare function formatUtamHtml(utamHtml: UtamHtml): string;
+/**
+ * Log what a UTAM object resolved to, for working out why a locator does not match.
+ *
+ * @param utamObject A UTAM page object or element.
+ * @param log Where the block is written. Defaults to `console.log`.
+ */
+export declare function logUtamHtml(utamObject: UtamElementLike, log?: (message: string) => void): Promise<void>;

package/lib/utam-html.js

@@ -0,0 +1,61 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const colors = {
+    reset: '\x1b[0m',
+    brightCyanBackground: '\x1b[106m',
+    cyan: '\x1b[36m',
+    green: '\x1b[32m',
+};
+/**
+ * Read the selector a UTAM object resolved through and its rendered HTML, shadow roots included.
+ *
+ * @param utamObject A UTAM page object or element.
+ */
+export async function getUtamHtml(utamObject) {
+    const element = utamObject.element.element;
+    return {
+        selector: describeSelector(element.selector),
+        html: await element.getHTML({ serializableShadowRoots: true }),
+    };
+}
+/**
+ * Render a `getUtamHtml` result as a colored block for a terminal.
+ *
+ * @param utamHtml The selector and HTML to render.
+ */
+export function formatUtamHtml(utamHtml) {
+    return (`${colors.brightCyanBackground}Logging UTAM Html${colors.reset} ${colors.cyan}selector${colors.reset} ` +
+        `${utamHtml.selector}\n${colors.green}${utamHtml.html}${colors.reset}`);
+}
+/**
+ * Log what a UTAM object resolved to, for working out why a locator does not match.
+ *
+ * @param utamObject A UTAM page object or element.
+ * @param log Where the block is written. Defaults to `console.log`.
+ */
+export async function logUtamHtml(utamObject, 
+// eslint-disable-next-line no-console -- logging is this function's purpose; `log` lets a caller redirect it
+log = (message) => console.log(message)) {
+    log(formatUtamHtml(await getUtamHtml(utamObject)));
+}
+function describeSelector(selector) {
+    if (typeof selector === 'string')
+        return selector;
+    if (typeof selector === 'function')
+        return selector.name || 'anonymous function';
+    return JSON.stringify(selector) ?? String(selector);
+}
+//# sourceMappingURL=utam-html.js.map

package/lib/utam-html.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utam-html.js","sourceRoot":"","sources":["../src/utam-html.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAkBH,MAAM,MAAM,GAAG;IACb,KAAK,EAAE,SAAS;IAChB,oBAAoB,EAAE,WAAW;IACjC,IAAI,EAAE,UAAU;IAChB,KAAK,EAAE,UAAU;CAClB,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,UAA2B;IAC3D,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC;IAC3C,OAAO;QACL,QAAQ,EAAE,gBAAgB,CAAC,OAAO,CAAC,QAAQ,CAAC;QAC5C,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,EAAE,uBAAuB,EAAE,IAAI,EAAE,CAAC;KAC/D,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,QAAkB;IAC/C,OAAO,CACL,GAAG,MAAM,CAAC,oBAAoB,oBAAoB,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,IAAI,WAAW,MAAM,CAAC,KAAK,GAAG;QACvG,GAAG,QAAQ,CAAC,QAAQ,KAAK,MAAM,CAAC,KAAK,GAAG,QAAQ,CAAC,IAAI,GAAG,MAAM,CAAC,KAAK,EAAE,CACvE,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,UAA2B;AAC3B,6GAA6G;AAC7G,MAAiC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;IAElE,GAAG,CAAC,cAAc,CAAC,MAAM,WAAW,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;AACrD,CAAC;AAED,SAAS,gBAAgB,CAAC,QAAiB;IACzC,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAClD,IAAI,OAAO,QAAQ,KAAK,UAAU;QAAE,OAAO,QAAQ,CAAC,IAAI,IAAI,oBAAoB,CAAC;IACjF,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC;AACtD,CAAC"}

package/package.json

@@ -0,0 +1,129 @@
+{
+  "name": "@simplysf/simply-utam-core",
+  "description": "Org authentication, Lightning navigation, and debugging helpers for UTAM UI tests against Salesforce",
+  "version": "0.0.0",
+  "author": "@ClayChipps",
+  "homepage": "https://github.com/SimplySF/simply-utam",
+  "bugs": "https://github.com/SimplySF/simply-utam/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SimplySF/simply-utam",
+    "directory": "packages/simply-utam-core"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": [
+    "/lib"
+  ],
+  "keywords": [
+    "utam",
+    "salesforce",
+    "webdriverio",
+    "ui-testing",
+    "simply"
+  ],
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "dependencies": {
+    "@salesforce/core": "^9.1.7"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.10",
+    "vitest": "^4.1.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "wireit",
+    "compile": "wireit",
+    "fix-license": "eslint src test --fix --rule \"header/header: [2]\"",
+    "format": "wireit",
+    "lint": "wireit",
+    "test": "wireit",
+    "test:coverage": "vitest run --coverage --project simply-utam-core",
+    "test:only": "wireit",
+    "test:watch": "vitest watch --project simply-utam-core"
+  },
+  "wireit": {
+    "build": {
+      "dependencies": [
+        "compile",
+        "lint"
+      ]
+    },
+    "compile": {
+      "command": "tsc -p . --pretty --incremental",
+      "files": [
+        "src/**/*.ts",
+        "**/tsconfig.json",
+        "../../tsconfig.json"
+      ],
+      "output": [
+        "lib/**",
+        "*.tsbuildinfo"
+      ],
+      "clean": "if-file-deleted"
+    },
+    "format": {
+      "command": "prettier --write \"+(src|test)/**/*.+(ts|js|json)\"",
+      "files": [
+        "src/**/*.ts",
+        "test/**/*.ts",
+        ".prettier*"
+      ],
+      "output": []
+    },
+    "lint": {
+      "command": "eslint src test --color --cache --cache-location .eslintcache",
+      "files": [
+        "src/**/*.ts",
+        "test/**/*.ts",
+        "**/.eslint*",
+        "**/tsconfig.json",
+        "../../eslint.config.mjs",
+        "../../tsconfig.json"
+      ],
+      "output": []
+    },
+    "test": {
+      "dependencies": [
+        "test:compile",
+        "test:only",
+        "lint"
+      ]
+    },
+    "test:compile": {
+      "command": "tsc -p \"./test\" --pretty",
+      "files": [
+        "test/**/*.ts",
+        "**/tsconfig.json",
+        "../../tsconfig.json"
+      ],
+      "output": []
+    },
+    "test:only": {
+      "command": "vitest run --project simply-utam-core",
+      "env": {
+        "FORCE_COLOR": "2"
+      },
+      "files": [
+        "test/**/*.ts",
+        "src/**/*.ts",
+        "**/tsconfig.json",
+        "../../tsconfig.json",
+        "../../vitest.config.ts"
+      ],
+      "output": []
+    }
+  }
+}