@salesforcedevs/sfdocs-e2e 0.6.132-linkfix-alpha

package/README.md

@@ -0,0 +1,63 @@
+# E2E for Content repo
+
+We can run e2e cases on example-repository
+
+Command to run
+
+```
+yarn test:e2e
+```
+
+# E2E for Portal
+
+To run portal e2e test cases, we need portal to run first.
+
+`yarn start:portal`
+
+Note: This will take a bit time as it will download all the required repositories mentioned in docsportal.config.json
+
+## How to run test cases
+
+Once the portal is running at localhost:3001, in a separate terminal - run
+
+`yarn test:e2e:portal`
+
+This will run the test cases as needed.
+
+### Browser compatibility test
+
+in doc-framework-monorepo/packages/e2e/portal-wdio-conf.js
+
+uncomment the below lines
+
+```
+    capabilities: [
+        // SFDOCs team: For chrome only. If we want debug check the above statement
+        defaultCapabilities[0],
+        {
+             browserName: 'firefox'
+        }
+    ],
+```
+
+### If you want to run with production URl
+
+in doc-framework-monorepo/packages/e2e/portal-wdio-conf.js
+
+change the `baseUrl` property as needed. For private space apps (as we need TMP auth) - we need to pass
+user pwd as below.
+
+```
+    //baseUrl:"https://beta:cloudwalker@beta.developer.salesforce.com",
+```
+
+### What if you want allure reports
+
+After that just run the below command
+
+```
+allure generate allure generate packages/e2e/_results_/allure-raw  --clean && allure open --clean && allure open
+```
+
+Note: If allure is not available in your PC, it may throw error.
+Please make sure either adding allure globally or run it from node_modules.

package/bin/run-e2e.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+
+/**
+ * CLI runner for @salesforcedevs/sfdocs-e2e
+ *
+ * This script allows running the SSG E2E tests from any repo that installs
+ * this package as an npm dependency.
+ *
+ * Usage:
+ *   sfdocs-e2e                                    # defaults: static-portal config, http://localhost:3000
+ *   sfdocs-e2e --baseUrl http://localhost:8080     # custom base URL
+ *   sfdocs-e2e --config portal                     # run portal tests (non-static)
+ *   sfdocs-e2e --config static-portal              # run static portal tests (default)
+ *   sfdocs-e2e --config search                     # run search tests
+ *
+ * Priority: CLI args > environment variables > defaults
+ *
+ * Environment variables:
+ *   E2E_BASE_URL          - Base URL of the site under test
+ *   CHROME_DRIVER_VERSION - Chrome driver version to use
+ */
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+// Parse CLI arguments
+const args = process.argv.slice(2);
+const parsedArgs = {};
+for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--baseUrl' && args[i + 1] && !args[i + 1].startsWith('--')) {
+        parsedArgs.baseUrl = args[++i];
+    } else if (args[i] === '--config' && args[i + 1] && !args[i + 1].startsWith('--')) {
+        parsedArgs.config = args[++i];
+    } else if (args[i] === '--help' || args[i] === '-h') {
+        console.log(`
+sfdocs-e2e - Run SSG E2E tests
+
+Usage:
+  sfdocs-e2e [options]
+
+Options:
+  --baseUrl <url>    Base URL of the site under test (default: http://localhost:3000)
+  --config <name>    WebdriverIO config to use: static-portal (default), portal, search
+  --help, -h         Show this help message
+
+Environment Variables:
+  E2E_BASE_URL            Override the base URL (CLI --baseUrl takes precedence)
+  CHROME_DRIVER_VERSION   Chrome driver version to use
+`);
+        process.exit(0);
+    }
+}
+
+// Resolve the config name
+const configName = parsedArgs.config || 'static-portal';
+const configMap = {
+    'static-portal': 'static-portal-wdio.conf.js',
+    portal: 'portal-wdio.conf.js',
+    search: 'search-wdio.conf.js',
+};
+
+const configFile = configMap[configName];
+if (!configFile) {
+    console.error(
+        `Unknown config: "${configName}". Available: ${Object.keys(configMap).join(', ')}`,
+    );
+    process.exit(1);
+}
+
+// The package root is one level up from bin/
+const packageRoot = path.resolve(__dirname, '..');
+const configPath = path.join(packageRoot, configFile);
+
+if (!fs.existsSync(configPath)) {
+    console.error(`Config file not found: ${configPath}`);
+    process.exit(1);
+}
+
+// Determine base URL: CLI arg > env var > default
+const baseUrl = parsedArgs.baseUrl || process.env.E2E_BASE_URL || 'http://localhost:3000';
+
+// Build the environment
+const env = {
+    ...process.env,
+    E2E_BASE_URL: baseUrl,
+    TS_NODE_TRANSPILE_ONLY: 'true',
+    TS_NODE_PROJECT: path.join(packageRoot, 'tsconfig.json'),
+};
+
+// Resolve the wdio binary - look in the package's own node_modules first, then fall back to the consuming project's node_modules
+let wdioBin;
+try {
+    wdioBin = require.resolve('@wdio/cli/bin/wdio', { paths: [packageRoot] });
+} catch {
+    try {
+        wdioBin = require.resolve('@wdio/cli/bin/wdio');
+    } catch {
+        console.error('Could not find @wdio/cli. Make sure it is installed.');
+        process.exit(1);
+    }
+}
+
+console.log(
+    `\n=== sfdocs-e2e ===\nConfig:   ${configName} (${configPath})\nBase URL: ${baseUrl}\nwdio:     ${wdioBin}\n==================\n`,
+);
+
+const result = spawnSync('node', [wdioBin, configPath], {
+    stdio: 'inherit',
+    env,
+    // Run from the package root so relative spec paths resolve correctly
+    cwd: packageRoot,
+});
+
+process.exit(result.status ?? 1);

package/common-wdio.conf.js

@@ -0,0 +1,402 @@
+const { execSync } = require('child_process');
+const debug = process.env.DEBUG;
+const video = require('wdio-video-reporter');
+
+/**
+ * Detects the full version of the locally installed Chrome (e.g. "145.0.7632.117").
+ * Returns the full version string, or undefined if detection fails.
+ */
+function detectChromeVersion() {
+    const chromeBinaries = [
+        'google-chrome --version',
+        'google-chrome-stable --version',
+        'chromium --version',
+        'chromium-browser --version',
+        // macOS
+        '"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --version',
+    ];
+    for (const cmd of chromeBinaries) {
+        try {
+            const output = execSync(cmd, {
+                encoding: 'utf8',
+                stdio: 'pipe',
+                timeout: 3000,
+            });
+            const match = output.match(/(\d+\.\d+\.\d+\.\d+)/);
+            if (match) return match[1];
+        } catch (_) {
+            // binary not found or timed out — try next
+        }
+    }
+    return undefined;
+}
+
+/**
+ * Resolves the ChromeDriver version that matches the locally installed Chrome.
+ * Skipped entirely in GitHub Actions where the pipeline sets CHROME_DRIVER_VERSION explicitly.
+ */
+function resolveChromedriverVersion() {
+    if (process.env.CHROME_DRIVER_VERSION) {
+        return process.env.CHROME_DRIVER_VERSION;
+    }
+    // Skip auto-detection in GitHub Actions — the pipeline sets CHROME_DRIVER_VERSION explicitly.
+    if (process.env.GITHUB_ACTIONS) {
+        return undefined;
+    }
+    const version = detectChromeVersion();
+    if (version) {
+        console.log(`[wdio] Auto-detected Chrome ${version}; using matching ChromeDriver version`);
+        return version;
+    }
+    console.warn(
+        '[wdio] Could not detect local Chrome version; using latest ChromeDriver (may mismatch)',
+    );
+    return undefined;
+}
+
+const defaultCapabilities = [
+    {
+        // maxInstances can get overwritten per capability. So if you have an in-house Selenium
+        // grid with only 5 firefox instances available you can make sure that not more than
+        // 5 instances get started at a time.
+        maxInstances: 1,
+        //
+        browserName: 'chrome',
+        'goog:chromeOptions': {
+            // (see https://developers.google.com/web/updates/2017/04/headless-chrome)
+            args: [
+                '--disable-gpu',
+                '--headless',
+                '--window-size=1920,1080',
+                '--no-sandbox',
+                '--disable-dev-shm-usage',
+            ],
+        },
+        acceptInsecureCerts: true,
+        // If outputDir is provided WebdriverIO can capture driver session logs
+        // it is possible to configure which logTypes to include/exclude.
+        // excludeDriverLogs: ['*'], // pass '*' to exclude all driver session logs
+        // excludeDriverLogs: ['bugreport', 'server'],
+    },
+];
+const defaultMochaTimeoutInterval = 200000; //increased timeout because its taking more time to load for references file
+
+// Resolve ChromeDriver version: env var → Chrome for Testing API lookup → latest
+const resolvedChromeDriverVersion = resolveChromedriverVersion();
+const chrome = resolvedChromeDriverVersion ? { version: resolvedChromeDriverVersion } : true;
+
+const drivers = {
+    // ChromeDriver 115+ is distributed via Chrome for Testing:
+    // https://googlechromelabs.github.io/chrome-for-testing/
+    chrome,
+    firefox: { version: '0.35.0' }, // https://github.com/mozilla/geckodriver/releases - 0.30.0+ supports ARM64 Mac
+};
+
+exports.config = {
+    //
+    // ====================
+    // Runner Configuration
+    // ====================
+    //
+    // WebdriverIO allows it to run your tests in arbitrary locations (e.g. locally or
+    // on a remote machine).
+    runner: 'local',
+    // Patterns to exclude.
+    exclude: [
+        // 'path/to/excluded/files'
+    ],
+    //
+    // ============
+    // Capabilities
+    // ============
+    // Define your capabilities here. WebdriverIO can run multiple capabilities at the same
+    // time. Depending on the number of capabilities, WebdriverIO launches several test
+    // sessions. Within your capabilities you can overwrite the spec and exclude options in
+    // order to group specific specs to a specific capability.
+    //
+    // First, you can define how many instances should be started at the same time. Let's
+    // say you have 3 different capabilities (Chrome, Firefox, and Safari) and you have
+    // set maxInstances to 1; wdio will spawn 3 processes. Therefore, if you have 10 spec
+    // files and you set maxInstances to 10, all spec files will get tested at the same time
+    // and 30 processes will get spawned. The property handles how many capabilities
+    // from the same test should run tests.
+    //
+    maxInstances: debug ? 1 : 5,
+    //
+    // If you have trouble getting all important capabilities together, check out the
+    // Sauce Labs platform configurator - a great tool to configure your capabilities:
+    // https://docs.saucelabs.com/reference/platforms-configurator
+    //
+    capabilities: debug
+        ? [{ browserName: 'chrome', acceptInsecureCerts: true }]
+        : defaultCapabilities,
+    //
+    // ===================
+    // Test Configurations
+    // ===================
+    // Define all options that are relevant for the WebdriverIO instance here
+    //
+    // Level of logging verbosity: trace | debug | info | warn | error | silent
+    logLevel: debug ? 'debug' : 'error',
+    //
+    // Set specific log levels per logger
+    // loggers:
+    // - webdriver, webdriverio
+    // - @wdio/applitools-service, @wdio/browserstack-service, @wdio/devtools-service, @wdio/sauce-service
+    // - @wdio/mocha-framework, @wdio/jasmine-framework
+    // - @wdio/local-runner
+    // - @wdio/sumologic-reporter
+    // - @wdio/cli, @wdio/config, @wdio/sync, @wdio/utils
+    // Level of logging verbosity: trace | debug | info | warn | error | silent
+    // logLevels: {
+    //     webdriver: 'info',
+    //     '@wdio/applitools-service': 'info'
+    // },
+    //
+    // If you only want to run your tests until a specific amount of tests have failed use
+    // bail (default is 0 - don't bail, run all tests).
+    bail: 0,
+    //
+    // Set a base URL in order to shorten url command calls. If your `url` parameter starts
+    // with `/`, the base url gets prepended, not including the path portion of your baseUrl.
+    // If your `url` parameter starts without a scheme or `/` (like `some/path`), the base url
+    // gets prepended directly.
+    baseUrl: process.env.E2E_BASE_URL || 'http://localhost:3000',
+    //
+    // Default timeout for all waitFor* commands.
+    waitforTimeout: 30000,
+    //
+    // Default timeout in milliseconds for request
+    // if browser driver or grid doesn't send response
+    connectionRetryTimeout: 120000,
+    //
+    // Default request retries count
+    connectionRetryCount: 3,
+
+    /* The number of times to retry an entire specfile when it fails as a whole.*/
+    specFileRetries: 1,
+
+    //
+    // Test runner services
+    // Services take over a specific job you don't want to take care of. They enhance
+    // your test setup with almost no effort. Unlike plugins, they don't add new
+    // commands. Instead, they hook themselves up into the test process.
+    services: [
+        [
+            'selenium-standalone',
+            {
+                installArgs: { drivers }, // drivers to install
+                args: { drivers }, // drivers to use
+            },
+        ],
+    ],
+
+    // Framework you want to run your specs with.
+    // The following are supported: Mocha, Jasmine, and Cucumber
+    // see also: https://webdriver.io/docs/frameworks.html
+    //
+    // Make sure you have the wdio adapter package for the specific framework installed
+    // before running any tests.
+    framework: 'mocha',
+    //
+    // The number of times to retry the entire specfile when it fails as a whole
+    // specFileRetries: 1,
+    //
+    // Delay in seconds between the spec file retry attempts
+    // specFileRetriesDelay: 0,
+    //
+    // Whether or not retried specfiles should be retried immediately or deferred to the end of the queue
+    // specFileRetriesDeferred: false,
+    //
+    // Test reporter for stdout.
+    // The only one supported by default is 'dot'
+    // see also: https://webdriver.io/docs/dot-reporter.html
+    reporters: [
+        'spec',
+        [
+            video,
+            {
+                saveAllVideos: false, // If true, also saves videos for successful test cases
+                videoSlowdownMultiplier: 3, // Higher to get slower videos, lower for faster videos [Value 1-100]
+            },
+        ],
+        [
+            'allure',
+            {
+                outputDir: './_results_/allure-raw',
+                disableWebdriverStepsReporting: true,
+                disableWebdriverScreenshotsReporting: false,
+            },
+        ],
+    ],
+
+    //
+    // Options to be passed to Mocha.
+    // See the full list at http://mochajs.org/
+    mochaOpts: {
+        // TypeScript setup
+        require: ['ts-node/register'],
+        ui: 'bdd',
+        timeout: debug ? 24 * 60 * 60 * 1000 : defaultMochaTimeoutInterval,
+    },
+    // For convenience, if ts-node or @babel/register modules are detected
+    // they are automatically loaded for config parsing so that TypeScript and
+    // future ES features can be used in wsdio configs, and are also
+    // automatically loaded for test running so that tests can be written
+    // using TypeScript and future ES features.
+    // Because this may not be ideal in every situation, the following options
+    // may be used to customize the loading for test running, incase it has
+    // other requirements.
+    autoCompileOpts: {
+        //
+        // To disable auto-loading entirely set this to false.
+        autoCompile: true, // <boolean> Disable this to turn off autoloading. Note: When disabling, you will need to handle calling any such libraries yourself.
+        //
+        // If you have ts-node installed, you can customize how options are passed to it here:
+        // Any valid ts-node config option is allowed. Alternatively the ENV Vars could also be used instead of this.
+        // See also: https://github.com/TypeStrong/ts-node#cli-and-programmatic-options
+        // See also RegisterOptions in https://github.com/TypeStrong/ts-node/blob/master/src/index.ts
+        tsNodeOpts: {
+            transpileOnly: true,
+            project: './tsconfig.json',
+        },
+        //
+        // If @babel/register is installed, you can customize how options are passed to it here:
+        // Any valid @babel/register config option is allowed.
+        // https://babeljs.io/docs/en/babel-register#specifying-options
+        babelOpts: {
+            ignore: [],
+        },
+    },
+    // Node arguments to specify when launching child processes.
+    execArgv: debug ? ['--inspect'] : [],
+    //
+    // =====
+    // Hooks
+    // =====
+    // WebdriverIO provides several hooks you can use to interfere with the test process in order to enhance
+    // it and to build services around it. You can either apply a single function or an array of
+    // methods to it. If one of them returns with a promise, WebdriverIO will wait until that promise got
+    // resolved to continue.
+    /**
+     * Gets executed once before all workers get launched.
+     * @param {Object} config wdio configuration object
+     * @param {Array.<Object>} capabilities list of capabilities details
+     */
+    // onPrepare: function (config, capabilities) {
+    // },
+    /**
+     * Gets executed before a worker process is spawned and can be used to initialise specific service
+     * for that worker as well as modify runtime environments in an async fashion.
+     * @param  {String} cid      capability id (e.g 0-0)
+     * @param  {[type]} caps     object containing capabilities for session that will be spawn in the worker
+     * @param  {[type]} specs    specs to be run in the worker process
+     * @param  {[type]} args     object that will be merged with the main configuration once worker is initialised
+     * @param  {[type]} execArgv list of string arguments passed to the worker process
+     */
+    // onWorkerStart: function (cid, caps, specs, args, execArgv) {
+    // },
+    /**
+     * Gets executed just before initialising the webdriver session and test framework. It allows you
+     * to manipulate configurations depending on the capability or spec.
+     * @param {Object} config wdio configuration object
+     * @param {Array.<Object>} capabilities list of capabilities details
+     * @param {Array.<String>} specs List of spec file paths that are to be run
+     */
+    // beforeSession: function (config, capabilities, specs) {
+    // },
+    /**
+     * Gets executed before test execution begins. At this point you can access to all global
+     * variables like `browser`. It is the perfect place to define custom commands.
+     * @param {Array.<Object>} capabilities list of capabilities details
+     * @param {Array.<String>} specs        List of spec file paths that are to be run
+     * @param {Object}         browser      instance of created browser/device session
+     */
+    // before: function (capabilities, specs) {
+    // },
+    /**
+     * Runs before a WebdriverIO command gets executed.
+     * @param {String} commandName hook command name
+     * @param {Array} args arguments that command would receive
+     */
+    // beforeCommand: function (commandName, args) {
+    // },
+    /**
+     * Hook that gets executed before the suite starts
+     * @param {Object} suite suite details
+     */
+    // beforeSuite: function (suite) {
+    // },
+    /**
+     * Function to be executed before a test (in Mocha/Jasmine) starts.
+     */
+    // beforeTest: function (test, context) {
+    // },
+    /**
+     * Hook that gets executed _before_ a hook within the suite starts (e.g. runs before calling
+     * beforeEach in Mocha)
+     */
+    // beforeHook: function (test, context) {
+    // },
+    /**
+     * Hook that gets executed _after_ a hook within the suite starts (e.g. runs after calling
+     * afterEach in Mocha)
+     */
+    // afterHook: function (test, context, { error, result, duration, passed, retries }) {
+    // },
+    /**
+     * Function to be executed after a test (in Mocha/Jasmine).
+     */
+    // afterTest: function(test, context, { error, result, duration, passed, retries }) {
+    // },
+
+    /**
+     * Hook that gets executed after the suite has ended
+     * @param {Object} suite suite details
+     */
+    // afterSuite: function (suite) {
+    // },
+    /**
+     * Runs after a WebdriverIO command gets executed
+     * @param {String} commandName hook command name
+     * @param {Array} args arguments that command would receive
+     * @param {Number} result 0 - command success, 1 - command error
+     * @param {Object} error error object if any
+     */
+    // afterCommand: function (commandName, args, result, error) {
+    // },
+    /**
+     * Gets executed after all tests are done. You still have access to all global variables from
+     * the test.
+     * @param {Number} result 0 - test pass, 1 - test fail
+     * @param {Array.<Object>} capabilities list of capabilities details
+     * @param {Array.<String>} specs List of spec file paths that ran
+     */
+    // after: function (result, capabilities, specs) {
+    // },
+    /**
+     * Gets executed right after terminating the webdriver session.
+     * @param {Object} config wdio configuration object
+     * @param {Array.<Object>} capabilities list of capabilities details
+     * @param {Array.<String>} specs List of spec file paths that ran
+     */
+    // afterSession: function (config, capabilities, specs) {
+    // },
+    /**
+     * Gets executed after all workers got shut down and the process is about to exit. An error
+     * thrown in the onComplete hook will result in the test run failing.
+     * @param {Object} exitCode 0 - success, 1 - fail
+     * @param {Object} config wdio configuration object
+     * @param {Array.<Object>} capabilities list of capabilities details
+     * @param {<Object>} results object containing test results
+     */
+    // onComplete: function(exitCode, config, capabilities, results) {
+    // },
+    /**
+     * Gets executed when a refresh happens.
+     * @param {String} oldSessionId session ID of the old session
+     * @param {String} newSessionId session ID of the new session
+     */
+    //onReload: function(oldSessionId, newSessionId) {
+    //}
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@salesforcedevs/sfdocs-e2e",
+  "version": "0.6.132-linkfix-alpha",
+  "description": "E2E test suite for SFDocs static portal pages (SSG)",
+  "license": "ISC",
+  "bin": {
+    "sfdocs-e2e": "./bin/run-e2e.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "*.conf.js",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "test:e2e": "TS_NODE_TRANSPILE_ONLY=true TS_NODE_PROJECT=./tsconfig.json wdio wdio.conf.js",
+    "test:e2e:portal": "TS_NODE_TRANSPILE_ONLY=true TS_NODE_PROJECT=./tsconfig.json wdio portal-wdio.conf.js",
+    "test:e2e:static:portal": "TS_NODE_TRANSPILE_ONLY=true TS_NODE_PROJECT=./tsconfig.json wdio static-portal-wdio.conf.js",
+    "test:scope-search": "TS_NODE_TRANSPILE_ONLY=true TS_NODE_PROJECT=./tsconfig.json wdio search-wdio.conf.js"
+  },
+  "dependencies": {
+    "@sa11y/wdio": "^7.0.0",
+    "@wdio/allure-reporter": "^7.19.0",
+    "@wdio/cli": "^7.19.0",
+    "@wdio/local-runner": "^7.19.0",
+    "@wdio/mocha-framework": "^7.19.0",
+    "@wdio/selenium-standalone-service": "^7.19.0",
+    "@wdio/spec-reporter": "^7.19.0",
+    "allure-commandline": "2.20.1",
+    "got": "^11.8.3",
+    "ts-node": "^10.9.1",
+    "typescript": "^4.1.3",
+    "wdio-video-reporter": "^3.4.0",
+    "webdriverio": "^7.19.0"
+  },
+  "devDependencies": {
+    "@types/mocha": "^10.0.1"
+  },
+  "gitHead": "5a9c6faeae5e1c7e337706b1f0dff51007ab702f"
+}

package/portal-wdio.conf.js

@@ -0,0 +1,7 @@
+const BASE_CONFIG = require('./common-wdio.conf');
+
+exports.config = {
+    ...BASE_CONFIG.config,
+    baseUrl: process.env.E2E_BASE_URL || 'http://localhost:3001',
+    specs: ['./src/portal/specs/**/*.test.ts', './src/shared/specs/*.test.ts'],
+};

package/search-wdio.conf.js

@@ -0,0 +1,10 @@
+const BASE_CONFIG = require('./common-wdio.conf');
+
+exports.config = {
+    ...BASE_CONFIG.config,
+    baseUrl: 'http://localhost:3001',
+    specs: [
+        './src/portal/specs/scope.search.reference.test.ts',
+        './src/portal/specs/scope.search.guide.test.ts',
+    ],
+};