@simplysf/simply-utam-core 0.0.0 → 0.1.0

package/lib/test-environment.js

@@ -16,12 +16,118 @@
 import { Org } from '@salesforce/core';
 /** The environment variable naming the org a UTAM run authenticates to. */
 export const USERNAME_ENV = 'UTAM_USERNAME';
+/**
+ * Default trusted Salesforce host regular expression patterns for Experience Cloud and Salesforce domains.
+ */
+export const DEFAULT_ALLOWED_HOST_PATTERNS = [
+    /\.salesforce\.com$/i,
+    /\.site\.com$/i,
+    /\.salesforce-sites\.com$/i,
+    /\.force\.com$/i,
+];
+function matchesCustomDomain(lowerHost, rawDomain) {
+    let cleanDomain = rawDomain;
+    if (cleanDomain.includes('://')) {
+        try {
+            cleanDomain = new URL(cleanDomain).hostname.toLowerCase();
+        }
+        catch {
+            // Keep cleanDomain on URL parse failure
+        }
+    }
+    if (cleanDomain.includes(':')) {
+        cleanDomain = cleanDomain.split(':')[0];
+    }
+    if (cleanDomain.startsWith('*.')) {
+        const suffix = cleanDomain.slice(2);
+        return lowerHost === suffix || lowerHost.endsWith(`.${suffix}`);
+    }
+    if (cleanDomain.startsWith('.')) {
+        const suffix = cleanDomain.slice(1);
+        return lowerHost === suffix || lowerHost.endsWith(`.${suffix}`);
+    }
+    return lowerHost === cleanDomain || lowerHost.endsWith(`.${cleanDomain}`);
+}
+/**
+ * Checks whether a given hostname is an authorized Salesforce or custom domain.
+ *
+ * @param hostname - The hostname to validate.
+ * @param instanceUrl - Optional base instance URL of the target org.
+ * @param envAllowedDomains - Comma-delimited custom allowed domains or wildcards.
+ * @returns True if the hostname is authorized, false otherwise.
+ */
+export function isHostAllowed(hostname, instanceUrl, envAllowedDomains = process.env['UTAM_ALLOWED_DOMAINS']) {
+    if (!hostname || typeof hostname !== 'string') {
+        return false;
+    }
+    let lowerHost = hostname.toLowerCase().trim();
+    if (lowerHost.includes(':')) {
+        lowerHost = lowerHost.split(':')[0];
+    }
+    if (!lowerHost) {
+        return false;
+    }
+    // 1. Check matching instance host
+    if (instanceUrl) {
+        try {
+            const parsedInstanceUrl = new URL(instanceUrl);
+            if (lowerHost === parsedInstanceUrl.hostname.toLowerCase()) {
+                return true;
+            }
+        }
+        catch {
+            // Ignore invalid instanceUrl parsing
+        }
+    }
+    // 2. Check default trusted Salesforce host patterns
+    if (DEFAULT_ALLOWED_HOST_PATTERNS.some((pattern) => pattern.test(lowerHost))) {
+        return true;
+    }
+    // 3. Check custom domain overrides (comma-separated list of domains or wildcards)
+    if (envAllowedDomains) {
+        const customDomains = envAllowedDomains
+            .split(',')
+            .map((d) => d.trim().toLowerCase())
+            .filter(Boolean);
+        return customDomains.some((domain) => matchesCustomDomain(lowerHost, domain));
+    }
+    return false;
+}
+/**
+ * Validates and parses a raw secure URL retrieved from SiteDetail.
+ *
+ * @param secureUrl - The raw secure URL string.
+ * @param siteId - Identifier of the site for error reporting.
+ * @param hostValidator - Optional callback function validating the hostname.
+ * @returns The parsed and validated WHATWG URL object.
+ */
+export function validateAndParseSecureUrl(secureUrl, siteId, hostValidator) {
+    if (!secureUrl) {
+        throw new Error(`SecureUrl is empty for Site ID '${siteId}'`);
+    }
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(secureUrl);
+    }
+    catch {
+        throw new Error(`Invalid Site URL '${secureUrl}' for Site ID '${siteId}'`);
+    }
+    if (parsedUrl.protocol !== 'https:') {
+        throw new Error(`Insecure protocol '${parsedUrl.protocol}' for Site URL: ${secureUrl}`);
+    }
+    if (typeof hostValidator === 'function' && !hostValidator(parsedUrl.hostname)) {
+        throw new Error(`Disallowed host '${parsedUrl.hostname}' for Site URL. Expected a trusted Salesforce domain or UTAM_ALLOWED_DOMAINS entry.`);
+    }
+    return parsedUrl;
+}
 /**
  * The org a UTAM run tests against, resolved from the Salesforce CLI's local auth store.
  */
 export class TestEnvironment {
     username;
+    #allowedDomains;
     #org;
+    #resolvedOrg;
     /**
      * Create a new environment for the given username, or `UTAM_USERNAME` when none is passed.
      *
@@ -33,14 +139,30 @@ export class TestEnvironment {
             throw new Error(`You must set a username using the ${USERNAME_ENV} env property for the test`);
         }
         this.username = username;
+        this.#allowedDomains = options.allowedDomains;
+    }
+    /**
+     * Indicates whether authentication has been initialized.
+     */
+    get isInitialized() {
+        return this.#resolvedOrg !== undefined;
     }
     /**
      * 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) => {
+        if (this.#resolvedOrg) {
+            return this.#resolvedOrg;
+        }
+        this.#org ??= Org.create({ aliasOrUsername: this.username })
+            .then((org) => {
+            this.#resolvedOrg = org;
+            return org;
+        })
+            .catch((error) => {
             this.#org = undefined;
+            this.#resolvedOrg = undefined;
             throw error;
         });
         return this.#org;
@@ -52,17 +174,193 @@ export class TestEnvironment {
     async init() {
         await this.getOrg();
     }
+    /**
+     * Returns the underlying `@salesforce/core` Connection instance.
+     */
+    async getConnection() {
+        const org = await this.getOrg();
+        return org.getConnection();
+    }
+    /**
+     * Returns the cleaned instance URL (My Domain) of the target org.
+     */
+    async getInstanceUrl() {
+        const org = await this.getOrg();
+        const rawUrl = org.getField(Org.Fields.INSTANCE_URL);
+        const instanceUrl = typeof rawUrl === 'string' ? rawUrl : '';
+        return instanceUrl.replace(/\/$/, '');
+    }
     /**
      * 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);
     }
+    /**
+     * Checks whether a hostname is authorized using the current target org context.
+     *
+     * @param hostname - The hostname to validate.
+     */
+    async isHostAllowedInternal(hostname) {
+        const org = await this.getOrg();
+        const rawUrl = org.getField(Org.Fields.INSTANCE_URL);
+        const instanceUrl = typeof rawUrl === 'string' ? rawUrl : undefined;
+        return isHostAllowed(hostname, instanceUrl, this.#allowedDomains);
+    }
+    /**
+     * Queries the Experience Cloud site and validates its SecureUrl.
+     */
+    async getValidatedExperienceSiteUrl(sitePrefix) {
+        const connection = await this.getConnection();
+        const queryStr = sitePrefix
+            ? `SELECT Id FROM Site WHERE UrlPathPrefix = '${sitePrefix.replace(/'/g, "\\'")}' LIMIT 1`
+            : `SELECT Id FROM Site WHERE UrlPathPrefix = null LIMIT 1`;
+        const siteResult = (await connection.query(queryStr));
+        if (!siteResult.records || siteResult.records.length === 0) {
+            throw new Error(`Unable to find an Experience Cloud site with prefix '${sitePrefix ?? 'none'}'`);
+        }
+        const siteId15 = siteResult.records[0].Id.substring(0, 15);
+        const siteDetailResult = (await connection.query(`SELECT SecureUrl FROM SiteDetail WHERE DurableId = '${siteId15}' LIMIT 1`));
+        if (!siteDetailResult.records || siteDetailResult.records.length === 0) {
+            throw new Error(`Unable to find SiteDetail for Site ID '${siteId15}'`);
+        }
+        const secureUrl = siteDetailResult.records[0].SecureUrl;
+        return validateAndParseSecureUrl(secureUrl, siteId15, (host) => isHostAllowed(host, undefined, this.#allowedDomains));
+    }
+    /**
+     * Generates a Frontdoor URL for an Experience Cloud Site using the singleaccess API.
+     *
+     * @param sitePrefix - Optional URL path prefix of the site.
+     * @param returnUrl - Optional landing page path after login.
+     * @returns One-time Experience Cloud frontdoor login URL.
+     */
+    async buildExperienceFrontdoorUrl(sitePrefix, returnUrl) {
+        const org = await this.getOrg();
+        await org.refreshAuth();
+        const connection = org.getConnection();
+        if (!connection.accessToken) {
+            throw new Error('Unable to retrieve an access token');
+        }
+        const parsedSiteUrl = await this.getValidatedExperienceSiteUrl(sitePrefix);
+        const singleAccessEndpoint = new URL('/services/oauth2/singleaccess', parsedSiteUrl.origin);
+        const responseRaw = await connection.request({
+            method: 'POST',
+            url: singleAccessEndpoint.href,
+            headers: {
+                accept: 'application/json',
+                'content-type': 'application/x-www-form-urlencoded',
+            },
+            body: '',
+        });
+        const responseData = typeof responseRaw === 'string'
+            ? JSON.parse(responseRaw)
+            : responseRaw;
+        const frontdoorUrl = responseData?.frontdoor_uri;
+        if (!frontdoorUrl) {
+            throw new Error('UI Bridge API response did not contain frontdoor_uri');
+        }
+        if (returnUrl) {
+            const cleanReturnUrl = returnUrl.startsWith('/') ? returnUrl : `/${returnUrl}`;
+            const separator = frontdoorUrl.includes('?') ? '&' : '?';
+            return `${frontdoorUrl}${separator}retURL=${encodeURIComponent(cleanReturnUrl)}`;
+        }
+        return frontdoorUrl;
+    }
+    /**
+     * Retrieves the Salesforce Organization ID dynamically via SOQL query.
+     */
+    async getOrgId() {
+        const connection = await this.getConnection();
+        const orgResult = (await connection.query('SELECT Id FROM Organization LIMIT 1'));
+        if (!orgResult.records || orgResult.records.length === 0) {
+            throw new Error('Unable to retrieve Organization ID');
+        }
+        return orgResult.records[0].Id;
+    }
+    /**
+     * Resolves a given Salesforce username to its corresponding User ID via SOQL query.
+     *
+     * @param username - Target Salesforce username to resolve.
+     */
+    async getUserIdByUsername(username) {
+        const connection = await this.getConnection();
+        const safeUsername = username.replace(/'/g, "\\'");
+        const userResult = (await connection.query(`SELECT Id FROM User WHERE Username = '${safeUsername}' LIMIT 1`));
+        if (!userResult.records || userResult.records.length === 0) {
+            throw new Error(`Unable to find user with username '${username}'`);
+        }
+        return userResult.records[0].Id;
+    }
+    /**
+     * Resolves an Experience Cloud Site's prefix to its corresponding 15-character Network ID.
+     *
+     * @param sitePrefix - The URL path prefix of the Experience site.
+     */
+    async getNetworkIdByPrefix(sitePrefix) {
+        const connection = await this.getConnection();
+        const queryStr = sitePrefix
+            ? `SELECT Id FROM Network WHERE UrlPathPrefix = '${sitePrefix.replace(/'/g, "\\'")}' LIMIT 1`
+            : `SELECT Id FROM Network WHERE UrlPathPrefix = null LIMIT 1`;
+        const networkResult = (await connection.query(queryStr));
+        if (!networkResult.records || networkResult.records.length === 0) {
+            throw new Error(`Unable to find a Network (Experience Site) with prefix '${sitePrefix ?? 'none'}'`);
+        }
+        return networkResult.records[0].Id.substring(0, 15);
+    }
+    /**
+     * Generates a fully qualified secure URL for a given Experience Cloud Site (Community).
+     *
+     * @param sitePrefix - The URL path prefix of the Experience site.
+     * @param path - Optional relative subpath to append.
+     */
+    async buildExperienceUrl(sitePrefix, path) {
+        const parsedSiteUrl = await this.getValidatedExperienceSiteUrl(sitePrefix);
+        const cleanSiteUrl = parsedSiteUrl.href.replace(/\/$/, '');
+        if (path) {
+            const cleanPath = path.startsWith('/') ? path : `/${path}`;
+            return `${cleanSiteUrl}${cleanPath}`;
+        }
+        return cleanSiteUrl;
+    }
+    /**
+     * Resets active connection state, requiring re-authentication on subsequent calls.
+     */
+    reset() {
+        this.#org = undefined;
+        this.#resolvedOrg = undefined;
+    }
+}
+let globalTestEnvironment = null;
+/**
+ * Returns the global singleton TestEnvironment instance, lazily creating it if necessary.
+ *
+ * @param options - Optional configuration options to initialize or overwrite the singleton.
+ * @returns The active TestEnvironment instance.
+ */
+export function getTestEnvironment(options) {
+    if (!globalTestEnvironment || options) {
+        globalTestEnvironment = new TestEnvironment(options);
+    }
+    return globalTestEnvironment;
+}
+/**
+ * Overrides the active global singleton TestEnvironment instance.
+ *
+ * @param instance - The TestEnvironment instance to set, or null to clear.
+ */
+export function setTestEnvironment(instance) {
+    globalTestEnvironment = instance;
+}
+/**
+ * Clears and resets the global singleton TestEnvironment instance.
+ */
+export function resetTestEnvironment() {
+    if (globalTestEnvironment) {
+        globalTestEnvironment.reset();
+    }
+    globalTestEnvironment = null;
 }
 //# sourceMappingURL=test-environment.js.map

package/lib/test-environment.js.map

@@ -1 +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"}
+{"version":3,"file":"test-environment.js","sourceRoot":"","sources":["../src/test-environment.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@simplysf/simply-utam-core",
   "description": "Org authentication, Lightning navigation, and debugging helpers for UTAM UI tests against Salesforce",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "author": "@ClayChipps",
   "homepage": "https://github.com/SimplySF/simply-utam",
   "bugs": "https://github.com/SimplySF/simply-utam/issues",
@@ -14,7 +14,8 @@
     "node": ">=22.0.0"
   },
   "files": [
-    "/lib"
+    "/lib",
+    "/templates"
   ],
   "keywords": [
     "utam",
@@ -31,10 +32,38 @@
     ".": {
       "types": "./lib/index.d.ts",
       "default": "./lib/index.js"
+    },
+    "./discovery": {
+      "types": "./lib/discovery/index.d.ts",
+      "default": "./lib/discovery/index.js"
+    },
+    "./rules": {
+      "types": "./lib/rules/index.d.ts",
+      "default": "./lib/rules/index.js"
+    },
+    "./overrides": {
+      "types": "./lib/overrides/index.d.ts",
+      "default": "./lib/overrides/index.js"
+    },
+    "./namespaces": {
+      "types": "./lib/namespaces/index.d.ts",
+      "default": "./lib/namespaces/index.js"
+    },
+    "./steps": {
+      "types": "./lib/steps/index.d.ts",
+      "default": "./lib/steps/index.js"
+    },
+    "./scaffold": {
+      "types": "./lib/scaffold/index.d.ts",
+      "default": "./lib/scaffold/index.js"
     }
   },
   "dependencies": {
-    "@salesforce/core": "^9.1.7"
+    "@cucumber/cucumber-expressions": "^20.1.0",
+    "@cucumber/gherkin": "^42.0.1",
+    "@cucumber/messages": "^34.2.1",
+    "@salesforce/core": "^9.2.0",
+    "prettier": "^3.9.6"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.10",
@@ -125,5 +154,6 @@
       ],
       "output": []
     }
-  }
+  },
+  "gitHead": "b3ad8b697cadea6ca67de58daccace6a18ed6d2a"
 }

package/templates/generator.config.json

@@ -0,0 +1,13 @@
+{
+  "inputRootDir": "./{{sourceDir}}",
+  "ignore": ["**/node_modules/**"],
+  "outputDir": "__utam__",
+  "relativeOutputDir": true,
+  "outputFileExtension": ".utam.json",
+  "overrideExisting": true,
+  "rulesFileMask": ["**/*.rules.json"],
+  "namespaces": {
+    "lightning": "salesforce-pageobjects/lightning/pageObjects/",
+    "c": "{{appName}}/pageObjects/"
+  }
+}

package/templates/hello.feature

@@ -0,0 +1,4 @@
+Feature: Salesforce UI Smoke Test
+
+  Scenario: Log in and navigate to Salesforce Home
+    Given I open the Salesforce application "Sales"

package/templates/hello.steps.mjs

@@ -0,0 +1,7 @@
+import { Given } from '@wdio/cucumber-framework';
+import { goToApplication } from '@simplysf/simply-utam';
+
+Given('I open the Salesforce application {string}', async (appName) => {
+  // Authenticates via Salesforce CLI frontdoor URL and opens the application home page
+  await goToApplication(appName);
+});

package/templates/namespace-map.json

@@ -0,0 +1,3 @@
+{
+  "{{appName}}/pageObjects/shared": "shared-components-pageobjects/pageObjects/shared"
+}

package/templates/utam.config.json

@@ -0,0 +1,9 @@
+{
+  "pageObjectsRootDir": "./",
+  "pageObjectsFileMask": ["**/__utam__/**/*.utam.json"],
+  "extensionsFileMask": ["**/__utam__/**/*.utam.js"],
+  "pageObjectsOutputDir": "pageObjects",
+  "extensionsOutputDir": "utils",
+  "moduleTarget": "module",
+  "skipCommonJs": true
+}

package/templates/wdio.conf.mjs

@@ -0,0 +1,68 @@
+import { UtamWdioService } from 'wdio-utam-service';
+
+const { DEBUG } = process.env;
+const EXPLICIT_TIMEOUT = 60 * 1000;
+const DEBUG_TIMEOUT = EXPLICIT_TIMEOUT * 30;
+
+export const config = {
+  runner: 'local',
+  specs: ['{{sourceDir}}/**/test/*.feature', '{{sourceDir}}/**/test/**/*.feature'],
+  maxInstances: 1,
+  capabilities: [
+    {
+      browserName: 'chrome',
+      'wdio:enforceWebDriverClassic': true,
+    },
+  ],
+  logLevel: 'debug',
+  bail: 0,
+  waitforTimeout: DEBUG ? DEBUG_TIMEOUT : EXPLICIT_TIMEOUT,
+  connectionRetryTimeout: 120000,
+  connectionRetryCount: 3,
+  automationProtocol: 'webdriver',
+  services: [
+    [
+      UtamWdioService,
+      {
+        implicitTimeout: 0,
+        injectionConfigs: ['salesforce-pageobjects/ui-global-components.config.json'],
+      },
+    ],
+  ],
+  framework: 'cucumber',
+  cucumberOpts: {
+    require: ['{{sourceDir}}/**/test/*.steps.mjs', '{{sourceDir}}/**/test/**/*.steps.mjs'],
+    timeout: 1000 * 30,
+  },
+  reporters: [
+    'spec',
+    [
+      'allure',
+      {
+        outputDir: 'allure-results',
+        disableWebdriverScreenshotesReporting: false,
+      },
+    ],
+  ],
+  screenshotPath: './errorShots/',
+  afterTest: async function (test, context, { passed }) {
+    if (!passed) {
+      await browser.takeScreenshot();
+    }
+  },
+  afterStep: async function (step, scenario, { error }) {
+    if (error) {
+      await browser.takeScreenshot();
+    }
+  },
+  afterScenario: async function (world, result) {
+    if (result.error) {
+      console.error('SCENARIO ERROR: ', result.error);
+    }
+  },
+  afterHook: async function (test, context, result) {
+    if (result.error) {
+      console.error('HOOK ERROR: ', result.error);
+    }
+  },
+};

package/templates/wireit.json

@@ -0,0 +1,37 @@
+{
+  "scripts": {
+    "build:utam-rules": "wireit",
+    "build:utam-generate": "wireit",
+    "build:utam-overrides": "wireit",
+    "build:utam-rewrite-namespaces": "wireit",
+    "build:utam": "wireit",
+    "test:ui": "wireit"
+  },
+  "wireit": {
+    "build:utam-rules": {
+      "command": "simply-utam rules"
+    },
+    "build:utam-generate": {
+      "command": "utam-generate -c generator.config.json",
+      "dependencies": ["build:utam-rules"]
+    },
+    "build:utam-overrides": {
+      "command": "simply-utam overrides",
+      "dependencies": ["build:utam-generate"]
+    },
+    "build:utam-rewrite-namespaces": {
+      "command": "simply-utam rewrite -c .utam/namespace-map.json",
+      "dependencies": ["build:utam-overrides"]
+    },
+    "build:utam": {
+      "command": "utam -c utam.config.json",
+      "files": ["**/__utam__/**/*.utam.json", "**/__utam__/**/*.utam.js"],
+      "output": ["pageObjects"],
+      "dependencies": ["build:utam-rewrite-namespaces"]
+    },
+    "test:ui": {
+      "command": "wdio run wdio.conf.mjs",
+      "dependencies": ["build:utam"]
+    }
+  }
+}