@simplysf/simply-utam-core 0.0.0 → 0.1.0

package/lib/index.js

@@ -20,8 +20,14 @@
 //
 // 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 { TestEnvironment, USERNAME_ENV, DEFAULT_ALLOWED_HOST_PATTERNS, isHostAllowed, validateAndParseSecureUrl, getTestEnvironment, setTestEnvironment, resetTestEnvironment, } from './test-environment.js';
 export { applicationPath, lightningAppName, newRecordPath, recordPath, relatedListPath } from './lightning-paths.js';
-export { LightningNavigator, } from './navigator.js';
+export { LightningNavigator, goToLoginUrl, goToExperiencePage, loginAsUser, loginAsExperienceUser, goToApplication, goToCreateNewRecord, goToRecord, goToRelatedList, resolveBrowser, } from './navigator.js';
 export { formatUtamHtml, getUtamHtml, logUtamHtml } from './utam-html.js';
+export { findLwcDirectories, discoverComponentsInPackageDir, discoverProject, } from './discovery/index.js';
+export { ROOT_TARGETS, convertLwcNameToHtml, getTargetsFromMeta, generateLwcRules, } from './rules/index.js';
+export { detectIndentation, findUtamOverridesFiles, walkElements, mergeElements, applyUtamOverrides, } from './overrides/index.js';
+export { findUtamJsonFiles, updateValueWithMappings, rewriteUtamNamespaces, } from './namespaces/index.js';
+export { parseGherkinDocument, extractStepsFromGherkin, normalizeExpression, extractStepExpressionsFromContent, compileStepExpressions, matchStepAgainstExpressions, formatParameterNames, generateStepSnippet, formatCode, resolveGlobs, resolveDefaultTargetOutput, generateCucumberSteps, } from './steps/index.js';
+export { DEFAULT_TEMPLATES_DIR, DEFAULT_REQUIRED_DEV_DEPENDENCIES, loadTemplate, generateGeneratorConfig, generateUtamConfig, generateWdioConfig, generateNamespaceMap, generateHelloFeature, generateHelloSteps, injectWireitConfiguration, checkMissingDependencies, scaffoldProject, } from './scaffold/index.js';
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +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"}
+{"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,EACL,eAAe,EACf,YAAY,EACZ,6BAA6B,EAC7B,aAAa,EACb,yBAAyB,EACzB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GAGrB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAErH,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,WAAW,EACX,qBAAqB,EACrB,eAAe,EACf,mBAAmB,EACnB,UAAU,EACV,eAAe,EACf,cAAc,GAIf,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,EAAuC,MAAM,gBAAgB,CAAC;AAE/G,OAAO,EACL,kBAAkB,EAClB,8BAA8B,EAC9B,eAAe,GAKhB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,GAIjB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,YAAY,EACZ,aAAa,EACb,kBAAkB,GAMnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,qBAAqB,GAKtB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,iCAAiC,EACjC,sBAAsB,EACtB,2BAA2B,EAC3B,oBAAoB,EACpB,mBAAmB,EACnB,UAAU,EACV,YAAY,EACZ,0BAA0B,EAC1B,qBAAqB,GAQtB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,qBAAqB,EACrB,iCAAiC,EACjC,YAAY,EACZ,uBAAuB,EACvB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,yBAAyB,EACzB,wBAAwB,EACxB,eAAe,GAGhB,MAAM,qBAAqB,CAAC"}

package/lib/namespaces/index.d.ts

@@ -0,0 +1 @@
+export * from './namespace-rewriter.js';

package/lib/namespaces/index.js

@@ -0,0 +1,17 @@
+/*
+ * 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.
+ */
+export * from './namespace-rewriter.js';
+//# sourceMappingURL=index.js.map

package/lib/namespaces/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/namespaces/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,cAAc,yBAAyB,CAAC"}

package/lib/namespaces/namespace-rewriter.d.ts

@@ -0,0 +1,50 @@
+export interface RewriteNamespacesOptions {
+    rootDir?: string;
+    sourceDirs?: string[];
+    configFile?: string;
+    mappings?: Record<string, string>;
+    dryRun?: boolean;
+    verbose?: boolean;
+}
+export interface NamespaceReplacement {
+    original: string;
+    updated: string;
+}
+export interface FileRewriteResult {
+    filePath: string;
+    changes: NamespaceReplacement[];
+    applied: boolean;
+    error?: string;
+}
+export interface RewriteNamespacesResult {
+    filesScanned: number;
+    filesModified: number;
+    totalReplacements: number;
+    dryRun: boolean;
+    configMissingOrEmpty: boolean;
+    notice?: string;
+    results: FileRewriteResult[];
+}
+/**
+ * Recursively locates all *.utam.json files in a directory.
+ *
+ * @param dirPath - Directory to search within.
+ * @returns Array of absolute paths to discovered *.utam.json files.
+ */
+export declare function findUtamJsonFiles(dirPath: string): string[];
+/**
+ * Recursively updates string values in a JSON structure based on sorted prefix mappings.
+ *
+ * @param value - Value or AST subtree to examine.
+ * @param sortedMappings - Tuples of [originalPrefix, replacementPrefix] sorted descending by length.
+ * @param changesList - Array recording applied namespace replacements.
+ * @returns Transformed value with replaced prefixes.
+ */
+export declare function updateValueWithMappings(value: unknown, sortedMappings: Array<[string, string]>, changesList: NamespaceReplacement[]): unknown;
+/**
+ * Rewrites namespace prefixes across compiled *.utam.json page object definitions.
+ *
+ * @param options - Namespace rewriting options.
+ * @returns Summary of files scanned and namespace replacements made.
+ */
+export declare function rewriteUtamNamespaces(options?: RewriteNamespacesOptions): RewriteNamespacesResult;

package/lib/namespaces/namespace-rewriter.js

@@ -0,0 +1,223 @@
+/*
+ * 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 fs from 'node:fs';
+import path from 'node:path';
+import { discoverProject } from '../discovery/index.js';
+import { detectIndentation } from '../overrides/index.js';
+/**
+ * Recursively locates all *.utam.json files in a directory.
+ *
+ * @param dirPath - Directory to search within.
+ * @returns Array of absolute paths to discovered *.utam.json files.
+ */
+export function findUtamJsonFiles(dirPath) {
+    const filesList = [];
+    try {
+        if (!fs.existsSync(dirPath)) {
+            return filesList;
+        }
+        const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dirPath, entry.name);
+            if (entry.isDirectory()) {
+                const name = entry.name;
+                if (name !== 'node_modules' &&
+                    name !== '.git' &&
+                    name !== 'dist' &&
+                    name !== 'lib' &&
+                    name !== '.wireit' &&
+                    name !== 'pageObjects' &&
+                    name !== 'allure-results') {
+                    filesList.push(...findUtamJsonFiles(fullPath));
+                }
+            }
+            else if (entry.isFile() && entry.name.endsWith('.utam.json')) {
+                filesList.push(fullPath);
+            }
+        }
+    }
+    catch {
+        // Gracefully ignore directory read errors
+    }
+    return filesList;
+}
+/**
+ * Recursively updates string values in a JSON structure based on sorted prefix mappings.
+ *
+ * @param value - Value or AST subtree to examine.
+ * @param sortedMappings - Tuples of [originalPrefix, replacementPrefix] sorted descending by length.
+ * @param changesList - Array recording applied namespace replacements.
+ * @returns Transformed value with replaced prefixes.
+ */
+export function updateValueWithMappings(value, sortedMappings, changesList) {
+    if (typeof value === 'string') {
+        for (const [prefix, replacement] of sortedMappings) {
+            if (value.startsWith(prefix)) {
+                const updated = replacement + value.slice(prefix.length);
+                changesList.push({ original: value, updated });
+                return updated;
+            }
+        }
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => updateValueWithMappings(item, sortedMappings, changesList));
+    }
+    if (value !== null && typeof value === 'object') {
+        const updatedObj = {};
+        for (const [key, val] of Object.entries(value)) {
+            updatedObj[key] = updateValueWithMappings(val, sortedMappings, changesList);
+        }
+        return updatedObj;
+    }
+    return value;
+}
+function resolveMappings(rootDir, configFile, mappings) {
+    let rawMappings = {};
+    if (mappings) {
+        rawMappings = mappings;
+    }
+    else {
+        const configPath = configFile
+            ? path.isAbsolute(configFile)
+                ? configFile
+                : path.resolve(rootDir, configFile)
+            : path.join(rootDir, '.utam', 'namespace-map.json');
+        if (!fs.existsSync(configPath)) {
+            return {
+                sortedMappings: [],
+                configMissingOrEmpty: true,
+                notice: `Namespace configuration file not found at ${configPath}. Exiting cleanly.`,
+            };
+        }
+        try {
+            const configContent = fs.readFileSync(configPath, 'utf-8');
+            const parsed = JSON.parse(configContent);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                rawMappings = parsed;
+            }
+        }
+        catch (err) {
+            return {
+                sortedMappings: [],
+                configMissingOrEmpty: true,
+                notice: `Failed to parse namespace config file: ${err.message}`,
+            };
+        }
+    }
+    const mappingEntries = Object.entries(rawMappings).filter(([prefix, replacement]) => typeof prefix === 'string' && prefix.trim() && typeof replacement === 'string');
+    if (mappingEntries.length === 0) {
+        return {
+            sortedMappings: [],
+            configMissingOrEmpty: true,
+            notice: 'Namespace mapping object is empty. No rewrites required.',
+        };
+    }
+    return {
+        sortedMappings: [...mappingEntries].sort((a, b) => b[0].length - a[0].length),
+        configMissingOrEmpty: false,
+    };
+}
+function processSingleUtamFile(file, sortedMappings, dryRun) {
+    let fileContent;
+    let originalJson;
+    try {
+        fileContent = fs.readFileSync(file, 'utf-8');
+        originalJson = JSON.parse(fileContent);
+    }
+    catch (err) {
+        return {
+            filePath: file,
+            changes: [],
+            applied: false,
+            error: `Failed to parse UTAM JSON: ${err.message}`,
+        };
+    }
+    const changesList = [];
+    const updatedJson = updateValueWithMappings(originalJson, sortedMappings, changesList);
+    if (changesList.length === 0) {
+        return {
+            filePath: file,
+            changes: [],
+            applied: false,
+        };
+    }
+    if (!dryRun) {
+        const indent = detectIndentation(fileContent);
+        const endsWithNewline = fileContent.endsWith('\n');
+        let outputContent = JSON.stringify(updatedJson, null, indent);
+        if (endsWithNewline && !outputContent.endsWith('\n')) {
+            outputContent += '\n';
+        }
+        fs.writeFileSync(file, outputContent, 'utf-8');
+    }
+    return {
+        filePath: file,
+        changes: changesList,
+        applied: true,
+    };
+}
+/**
+ * Rewrites namespace prefixes across compiled *.utam.json page object definitions.
+ *
+ * @param options - Namespace rewriting options.
+ * @returns Summary of files scanned and namespace replacements made.
+ */
+export function rewriteUtamNamespaces(options = {}) {
+    const rootDir = path.resolve(options.rootDir ?? process.cwd());
+    const dryRun = Boolean(options.dryRun);
+    const resolution = resolveMappings(rootDir, options.configFile, options.mappings);
+    if (resolution.configMissingOrEmpty) {
+        return {
+            filesScanned: 0,
+            filesModified: 0,
+            totalReplacements: 0,
+            dryRun,
+            configMissingOrEmpty: true,
+            notice: resolution.notice,
+            results: [],
+        };
+    }
+    let sourceDirs = options.sourceDirs;
+    if (!sourceDirs || sourceDirs.length === 0) {
+        const discovered = discoverProject(rootDir);
+        sourceDirs = discovered.packageDirectories.length > 0 ? discovered.packageDirectories : ['./sfdx-source'];
+    }
+    const allUtamFiles = [];
+    for (const sourceDir of sourceDirs) {
+        const resolvedSource = path.isAbsolute(sourceDir) ? sourceDir : path.resolve(rootDir, sourceDir);
+        allUtamFiles.push(...findUtamJsonFiles(resolvedSource));
+    }
+    const uniqueUtamFiles = Array.from(new Set(allUtamFiles));
+    const result = {
+        filesScanned: uniqueUtamFiles.length,
+        filesModified: 0,
+        totalReplacements: 0,
+        dryRun,
+        configMissingOrEmpty: false,
+        results: [],
+    };
+    for (const file of uniqueUtamFiles) {
+        const fileResult = processSingleUtamFile(file, resolution.sortedMappings, dryRun);
+        if (fileResult.applied) {
+            result.filesModified++;
+            result.totalReplacements += fileResult.changes.length;
+        }
+        result.results.push(fileResult);
+    }
+    return result;
+}
+//# sourceMappingURL=namespace-rewriter.js.map

package/lib/namespaces/namespace-rewriter.js.map

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

package/lib/navigator.d.ts

@@ -1,3 +1,4 @@
+import { TestEnvironment } from './test-environment.js';
 /** The part of a WebdriverIO browser the navigator drives. */
 export type NavigableBrowser = {
     navigateTo(url: string): Promise<unknown>;
@@ -5,6 +6,12 @@ export type NavigableBrowser = {
 /** Anything that can mint a logged-in URL; `TestEnvironment` in practice. */
 export type FrontdoorUrlSource = {
     buildFrontdoorUrl(returnUrl?: string): Promise<string>;
+    buildExperienceFrontdoorUrl?(sitePrefix?: string, returnUrl?: string): Promise<string>;
+    getOrgId?(): Promise<string>;
+    getUserIdByUsername?(username: string): Promise<string>;
+    getInstanceUrl?(): Promise<string>;
+    getNetworkIdByPrefix?(sitePrefix?: string): Promise<string>;
+    buildExperienceUrl?(sitePrefix?: string, path?: string): Promise<string>;
 };
 export type LightningNavigatorOptions = {
     /** Where login URLs come from. Defaults to a `TestEnvironment` for `UTAM_USERNAME`. */
@@ -12,6 +19,16 @@ export type LightningNavigatorOptions = {
     /** The browser to drive. Defaults to WebdriverIO's global `browser`, looked up on each call. */
     browser?: NavigableBrowser;
 };
+declare global {
+    var browser: NavigableBrowser | undefined;
+}
+/**
+ * Resolves an active browser instance from explicit parameters or the global runtime context.
+ *
+ * @param browserInstance - Optional explicit browser instance.
+ * @returns The resolved NavigableBrowser instance.
+ */
+export declare function resolveBrowser(browserInstance?: NavigableBrowser): 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.
@@ -28,34 +45,145 @@ export declare class LightningNavigator {
      * Log in and open `returnUrl`, or the org's default landing page when it is omitted.
      *
      * @param returnUrl Path to open after login.
+     * @returns The resolved frontdoor URL navigated to.
      */
-    goToLoginUrl(returnUrl?: string): Promise<void>;
+    goToLoginUrl(returnUrl?: string): Promise<string>;
     /**
      * Log in and open a Lightning app's home page.
      *
      * @param applicationName The app's developer name; see `lightningAppName` for namespacing.
+     * @returns The resolved application URL.
      */
-    goToApplication(applicationName: string): Promise<void>;
+    goToApplication(applicationName: string): Promise<string>;
     /**
      * 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.
+     * @returns The resolved record creation URL.
      */
-    goToCreateNewRecord(applicationName: string, objectApiName: string): Promise<void>;
+    goToCreateNewRecord(applicationName: string, objectApiName: string): Promise<string>;
     /**
      * Log in and open a record's detail page.
      *
      * @param applicationName The app's developer name.
      * @param recordId The record's id.
+     * @returns The resolved record view URL.
      */
-    goToRecord(applicationName: string, recordId: string): Promise<void>;
+    goToRecord(applicationName: string, recordId: string): Promise<string>;
     /**
      * 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.
+     * @returns The resolved related list URL.
+     */
+    goToRelatedList(applicationName: string, recordId: string, relatedListName: string): Promise<string>;
+    /**
+     * Navigates the browser to a specific Experience Cloud site page via UI Bridge frontdoor login.
+     *
+     * @param sitePrefix - The URL prefix of the Experience site.
+     * @param pageName - The Experience page name (relative to /s/).
+     * @returns The resolved Experience frontdoor URL navigated to.
+     */
+    goToExperiencePage(sitePrefix: string, pageName: string): Promise<string>;
+    /**
+     * Logs in as a specific user using Salesforce user impersonation.
+     *
+     * @param username - The target user's username.
+     * @param returnUrl - The target page to land on once logged in. Defaults to '/'.
+     * @returns The resolved impersonation redirect URL.
      */
-    goToRelatedList(applicationName: string, recordId: string, relatedListName: string): Promise<void>;
+    loginAsUser(username: string, returnUrl?: string): Promise<string>;
+    /**
+     * Logs in as a specific user and navigates directly to an Experience Cloud site.
+     *
+     * @param username - The target user's username.
+     * @param sitePrefix - The URL prefix of the Experience site.
+     * @param pageName - The Experience page name (relative to /s/).
+     * @returns The resolved Experience site page URL.
+     */
+    loginAsExperienceUser(username: string, sitePrefix: string, pageName: string): Promise<string>;
+    resolveBrowser(): NavigableBrowser;
 }
+/**
+ * Functional helper: Navigates the browser to the Salesforce Frontdoor login URL.
+ *
+ * @param returnUrl - Optional landing page path after login.
+ * @param browserInstance - Optional browser instance overriding the global runner.
+ * @param testEnvironment - Optional TestEnvironment instance.
+ * @returns The resolved frontdoor URL navigated to.
+ */
+export declare function goToLoginUrl(returnUrl?: string, browserInstance?: NavigableBrowser, testEnvironment?: TestEnvironment): Promise<string>;
+/**
+ * Functional helper: Navigates the browser to an Experience Cloud page.
+ *
+ * @param sitePrefix - The URL prefix of the Experience site.
+ * @param pageName - The Experience page name.
+ * @param browserInstance - Optional browser instance overriding the global runner.
+ * @param testEnvironment - Optional TestEnvironment instance.
+ * @returns The resolved Experience frontdoor URL navigated to.
+ */
+export declare function goToExperiencePage(sitePrefix: string, pageName: string, browserInstance?: NavigableBrowser, testEnvironment?: TestEnvironment): Promise<string>;
+/**
+ * Functional helper: Logs in as a specific user using Salesforce user impersonation.
+ *
+ * @param username - The target user's username.
+ * @param returnUrl - Landing path after impersonation.
+ * @param browserInstance - Optional browser instance overriding the global runner.
+ * @param testEnvironment - Optional TestEnvironment instance.
+ * @returns The resolved impersonation redirect URL.
+ */
+export declare function loginAsUser(username: string, returnUrl?: string, browserInstance?: NavigableBrowser, testEnvironment?: TestEnvironment): Promise<string>;
+/**
+ * Functional helper: Logs in as a user and navigates directly to an Experience Cloud site.
+ *
+ * @param username - The target user's username.
+ * @param sitePrefix - The URL prefix of the Experience site.
+ * @param pageName - The Experience page name.
+ * @param browserInstance - Optional browser instance overriding the global runner.
+ * @param testEnvironment - Optional TestEnvironment instance.
+ * @returns The resolved Experience site page URL.
+ */
+export declare function loginAsExperienceUser(username: string, sitePrefix: string, pageName: string, browserInstance?: NavigableBrowser, testEnvironment?: TestEnvironment): Promise<string>;
+/**
+ * Functional helper: Navigates to a standard Lightning Application home page.
+ *
+ * @param applicationName - The developer name of the Lightning application.
+ * @param browserInstance - Optional browser instance.
+ * @param testEnvironment - Optional TestEnvironment instance.
+ * @returns The resolved frontdoor application URL.
+ */
+export declare function goToApplication(applicationName: string, browserInstance?: NavigableBrowser, testEnvironment?: TestEnvironment): Promise<string>;
+/**
+ * Functional helper: Navigates to a new record creation page for a specific sObject in an application.
+ *
+ * @param applicationName - The developer name of the Lightning application.
+ * @param objectName - The API name of the sObject.
+ * @param browserInstance - Optional browser instance.
+ * @param testEnvironment - Optional TestEnvironment instance.
+ * @returns The resolved frontdoor URL.
+ */
+export declare function goToCreateNewRecord(applicationName: string, objectName: string, browserInstance?: NavigableBrowser, testEnvironment?: TestEnvironment): Promise<string>;
+/**
+ * Functional helper: Navigates to a record view page in a Lightning application.
+ *
+ * @param applicationName - The developer name of the Lightning application.
+ * @param recordId - The 15 or 18 character Salesforce record ID.
+ * @param browserInstance - Optional browser instance.
+ * @param testEnvironment - Optional TestEnvironment instance.
+ * @returns The resolved frontdoor URL.
+ */
+export declare function goToRecord(applicationName: string, recordId: string, browserInstance?: NavigableBrowser, testEnvironment?: TestEnvironment): Promise<string>;
+/**
+ * Functional helper: Navigates to a related list view for a specific record in a Lightning application.
+ *
+ * @param applicationName - The developer name of the Lightning application.
+ * @param recordId - The 15 or 18 character parent record ID.
+ * @param relatedListName - The relationship name of the related list.
+ * @param browserInstance - Optional browser instance.
+ * @param testEnvironment - Optional TestEnvironment instance.
+ * @returns The resolved frontdoor URL.
+ */
+export declare function goToRelatedList(applicationName: string, recordId: string, relatedListName: string, browserInstance?: NavigableBrowser, testEnvironment?: TestEnvironment): Promise<string>;