@salesforcedevs/sfdocs-e2e 0.6.134-alpha203 → 0.6.139-node22-3

package/README.md

@@ -1,63 +1,209 @@
-# E2E for Content repo
+# @salesforcedevs/sfdocs-e2e
 
-We can run e2e cases on example-repository
+End-to-end test suite for SFDocs portal pages, built on [WebdriverIO](https://webdriver.io/) + Mocha. It runs headless Chrome tests against a live (or locally served) SFDocs portal and generates Allure reports with video recordings on failure.
 
-Command to run
+This package is **published independently** from the rest of the monorepo. It is not released as part of the standard `yarn release` workflow — see [Publishing](#publishing) below.
 
-```
-yarn test:e2e
+---
+
+## What it tests
+
+Tests are organised into three suites, each targeting a different surface:
+
+| Suite           | Config file                  | Default base URL        | Spec paths                                |
+| --------------- | ---------------------------- | ----------------------- | ----------------------------------------- |
+| `static-portal` | `static-portal-wdio.conf.js` | `http://localhost:3000` | `src/portal/specs/`, `src/shared/specs/`  |
+| `portal`        | `portal-wdio.conf.js`        | `http://localhost:3001` | `src/portal/specs/`, `src/shared/specs/`  |
+| `search`        | `search-wdio.conf.js`        | `http://localhost:3000` | `src/portal/specs/scope.search.*.test.ts` |
+
+**Shared specs** (`src/shared/specs/`) cover UI components that exist on both portal and content-repo pages:
+
+- Anchor headings, banners, breadcrumbs, callout content
+- Code blocks, doc phase badges, dev-center links
+- Error routes, guides, overview pages, page titles
+- Redoc references, references, videos
+
+**Portal specs** (`src/portal/specs/`) cover portal-specific pages:
+
+- `/docs` landing page, `/docs/apis` landing page
+- Media mapper, scoped search (guides and references)
+
+**Content-repo specs** (`src/content-repo/specs/`) cover the content-repository portal:
+
+- Homepage, guide and reference pages, component specifications
+- Nav header, tabset, media mapper, sitemap
+
+---
+
+## Running tests locally
+
+### Prerequisites
+
+- Node.js and Yarn installed
+- Google Chrome installed (ChromeDriver version is auto-detected from your local Chrome installation)
+- A running SFDocs portal at the target base URL
+
+The `static-portal` suite excludes the following tests that are not applicable to static builds:
+
+- `docs.api.test.ts` and `docs.test.ts` — landing pages that don't exist in static builds
+- Footer tests (`should display footer`) — footer component is not available in static builds
+
+### Run against the static portal (default)
+
+```bash
+# 1. Build and serve the static portal (from the monorepo root or example-portal package)
+yarn build:static:portal
+yarn start:static:portal   # serves on http://localhost:3000
+
+# 2. Run the static-portal suite
+yarn test:e2e:static:portal
 ```
 
-# E2E for Portal
+### Run against the live portal
 
-To run portal e2e test cases, we need portal to run first.
+```bash
+# Portal must be running on http://localhost:3001
+yarn test:e2e:portal
+```
 
-`yarn start:portal`
+### Run scope search tests
 
-Note: This will take a bit time as it will download all the required repositories mentioned in docsportal.config.json
+```bash
+yarn test:scope-search
+```
 
-## How to run test cases
+### Override the base URL
 
-Once the portal is running at localhost:3001, in a separate terminal - run
+Pass the `E2E_BASE_URL` environment variable to point tests at any environment:
 
-`yarn test:e2e:portal`
+```bash
+E2E_BASE_URL=https://staging.example.com yarn test:e2e:static:portal
+```
 
-This will run the test cases as needed.
+---
 
-### Browser compatibility test
+## Using as a CLI in external projects
 
-in doc-framework-monorepo/packages/e2e/portal-wdio-conf.js
+This package ships a `sfdocs-e2e` binary so consuming projects can run the suite without cloning this repo.
 
-uncomment the below lines
+### Install
 
+```bash
+npm install --save-dev @salesforcedevs/sfdocs-e2e
+# or
+yarn add --dev @salesforcedevs/sfdocs-e2e
 ```
-    capabilities: [
-        // SFDOCs team: For chrome only. If we want debug check the above statement
-        defaultCapabilities[0],
-        {
-             browserName: 'firefox'
-        }
-    ],
+
+### Run
+
+```bash
+# Defaults: static-portal config, http://localhost:3000
+npx sfdocs-e2e
+
+# Custom base URL
+npx sfdocs-e2e --baseUrl http://localhost:8080
+
+# Choose a config suite
+npx sfdocs-e2e --config portal
+npx sfdocs-e2e --config static-portal
+npx sfdocs-e2e --config static-dsc-portal
+npx sfdocs-e2e --config search
+
+# Help
+npx sfdocs-e2e --help
 ```
 
-### If you want to run with production URl
+### Environment variables
 
-in doc-framework-monorepo/packages/e2e/portal-wdio-conf.js
+| Variable                | Description                                                                       |
+| ----------------------- | --------------------------------------------------------------------------------- |
+| `E2E_BASE_URL`          | Base URL of the site under test (overridden by `--baseUrl`)                       |
+| `CHROME_DRIVER_VERSION` | Pin a specific ChromeDriver version (auto-detected locally; set explicitly in CI) |
 
-change the `baseUrl` property as needed. For private space apps (as we need TMP auth) - we need to pass
-user pwd as below.
+---
+
+## Test results and reports
+
+Results are written to `_results_/` inside the package directory:
 
 ```
-    //baseUrl:"https://beta:cloudwalker@beta.developer.salesforce.com",
+_results_/
+  static-portal/
+    allure-raw/        # Allure XML + video attachments
+    videos/            # MP4 recordings of failed tests
+    wdio-*.log         # Browser driver logs
+```
+
+To generate and open an Allure HTML report:
+
+```bash
+npx allure generate _results_/static-portal/allure-raw -o _results_/static-portal/allure-report --clean
+npx allure open _results_/static-portal/allure-report
+```
+
+---
+
+## Publishing
+
+This package is **excluded from the monorepo's standard release script** (`scripts/release_npm.sh`) because it is an independent test utility with its own release cadence.
+
+### When to publish
+
+Publish a new version when:
+
+- New test suites or specs are added
+- The CLI runner (`bin/run-e2e.js`) is updated
+- WebdriverIO or other test dependencies are upgraded
+- Config files are changed in a way that affects consumers
+
+### How to publish
+
+Always validate with an alpha release first, then promote to stable.
+
+The e2e package is marked `"private": true` so it is automatically skipped during the monorepo's standard `yarn release` workflow. Two convenience scripts handle temporarily removing the private flag, publishing, and restoring it:
+
+| Script              | Command                            | Description                        |
+| ------------------- | ---------------------------------- | ---------------------------------- |
+| `release:alpha:e2e` | `yarn release:alpha:e2e <version>` | Publish with the `alpha` dist-tag  |
+| `release:e2e`       | `yarn release:e2e <version>`       | Publish with the `latest` dist-tag |
+
+**1. Publish an alpha (for testing)**
+
+```bash
+cd packages/e2e
+yarn release:alpha:e2e 1.0.0-alpha.0
 ```
 
-### What if you want allure reports
+The `alpha` dist-tag means `yarn add @salesforcedevs/sfdocs-e2e` will **not** resolve this version by default — consumers must opt in explicitly:
 
-After that just run the below command
+```bash
+# Install latest alpha
+yarn add --dev @salesforcedevs/sfdocs-e2e@alpha
 
+# Or pin to a specific alpha version
+yarn add --dev @salesforcedevs/sfdocs-e2e@1.0.0-alpha.0
 ```
-allure generate allure generate packages/e2e/_results_/allure-raw  --clean && allure open --clean && allure open
+
+Iterate on alphas as needed (`1.0.0-alpha.1`, `1.0.0-alpha.2`, ...) until the release is validated.
+
+**2. Promote to stable**
+
+```bash
+cd packages/e2e
+yarn release:e2e 1.0.0
 ```
 
-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.
+**3. Future releases — bump and publish**
+
+```bash
+cd packages/e2e
+
+# Bug fix
+yarn release:e2e 1.0.1
+
+# New feature
+yarn release:e2e 1.1.0
+
+# Breaking change
+yarn release:e2e 2.0.0
+```

package/bin/publish.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+VERSION="${1:?Usage: publish.sh <version> [--tag <tag>]}"
+shift
+
+cp package.json .package.json.bak
+
+cleanup() {
+  mv .package.json.bak package.json
+  node -e "
+    var p = require('./package.json');
+    p.version = '$VERSION';
+    require('fs').writeFileSync('package.json', JSON.stringify(p, null, 2) + '\n');
+  "
+  git add package.json
+  git commit --amend --no-edit
+}
+trap cleanup EXIT
+
+node -e "
+  var p = require('./package.json');
+  delete p.private;
+  require('fs').writeFileSync('package.json', JSON.stringify(p, null, 2) + '\n');
+"
+
+if [ "$#" -gt 0 ]; then
+  yarn publish --new-version "$VERSION" "$@"
+else
+  yarn publish --new-version "$VERSION"
+fi

package/bin/run-e2e.js

@@ -56,6 +56,7 @@ Environment Variables:
 const configName = parsedArgs.config || 'static-portal';
 const configMap = {
     'static-portal': 'static-portal-wdio.conf.js',
+    'static-dsc-portal': 'static-dsc-portal-wdio.conf.js',
     portal: 'portal-wdio.conf.js',
     search: 'search-wdio.conf.js',
 };

package/common-wdio.conf.js

@@ -80,6 +80,7 @@ const defaultCapabilities = [
     },
 ];
 const defaultMochaTimeoutInterval = 200000; //increased timeout because its taking more time to load for references file
+const isGithubActions = Boolean(process.env.GITHUB_ACTIONS);
 
 // Resolve ChromeDriver version: env var → Chrome for Testing API lookup → latest
 const resolvedChromeDriverVersion = resolveChromedriverVersion();
@@ -181,15 +182,25 @@ exports.config = {
     // 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
-            },
-        ],
-    ],
+    services: isGithubActions
+        ? []
+        : [
+              [
+                  'selenium-standalone',
+                  {
+                      installArgs: { drivers }, // drivers to install
+                      args: { drivers }, // drivers to use
+                  },
+              ],
+          ],
+    ...(isGithubActions
+        ? {
+              protocol: 'http',
+              hostname: '127.0.0.1',
+              port: 4444,
+              path: '/wd/hub',
+          }
+        : {}),
 
     // Framework you want to run your specs with.
     // The following are supported: Mocha, Jasmine, and Cucumber

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforcedevs/sfdocs-e2e",
-  "version": "0.6.134-alpha203",
+  "version": "0.6.139-node22-3",
   "description": "E2E test suite for SFDocs static portal pages (SSG)",
   "license": "ISC",
   "bin": {
@@ -16,10 +16,13 @@
     "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"
+    "test:e2e:static:dsc:portal": "TS_NODE_TRANSPILE_ONLY=true TS_NODE_PROJECT=./tsconfig.json wdio static-dsc-portal-wdio.conf.js",
+    "test:scope-search": "TS_NODE_TRANSPILE_ONLY=true TS_NODE_PROJECT=./tsconfig.json wdio search-wdio.conf.js",
+    "release:alpha:e2e": "f() { bash bin/publish.sh $1 --tag alpha; }; f",
+    "release:e2e": "f() { bash bin/publish.sh $1; }; f"
   },
   "dependencies": {
-    "@sa11y/wdio": "^7.0.0",
+    "@sa11y/wdio": "^8.0.0",
     "@wdio/allure-reporter": "^7.19.0",
     "@wdio/cli": "^7.19.0",
     "@wdio/local-runner": "^7.19.0",
@@ -35,6 +38,5 @@
   },
   "devDependencies": {
     "@types/mocha": "^10.0.1"
-  },
-  "gitHead": "7159a015481c77999404c8ee2a324bd5e89f6e1e"
+  }
 }

package/src/content-repo/specs/homepage.test.ts

@@ -13,7 +13,7 @@ describe('Homepage', () => {
     it('should show the expected number of projects', async () => {
         const projectCards = await HomePage.projectCards;
 
-        expect(projectCards.length).toEqual(17);
+        expect(projectCards.length).toEqual(19);
     });
 
     // it('is accessible', () => {

package/src/shared/pageobjects/page.ts

@@ -44,15 +44,15 @@ export default class Page {
         );
     }
 
-    async getHeader(): Promise<WebdriverIO.Element> {
-        return await $('hgf-c360contextnav');
+    async getHeader(headerTag = 'dx-global-header'): Promise<WebdriverIO.Element> {
+        return await $(headerTag);
     }
 
     async getHeaderTitle(): Promise<WebdriverIO.Element> {
         return (await $('>>>header')).$('h4');
     }
 
-    async getGlobalSearchBox(headerTag = 'dx-header'): Promise<WebdriverIO.Element> {
+    async getGlobalSearchBox(headerTag = 'dx-global-header'): Promise<WebdriverIO.Element> {
         return (await $(headerTag)).shadow$('dx-header-search');
     }
 

package/src/shared/specs/internalLinks.test.ts

@@ -0,0 +1,70 @@
+import GuidePage from '../pageobjects/guide.page';
+
+/**
+ * E2E tests for internal link resolution (internalReferencePlugin + referenceLinkTransformerPlugin).
+ * Covered: relative .md → .html resolution, guide-to-guide links, reference-to-guide links,
+ * external links.
+ **/
+describe('Internal link resolution', () => {
+    const UPDATE_ORDER_STATES_PAGE =
+        '/docs/commerce/test-cc-orders-api/guide/update-order-states.html';
+    const QUICK_START_PAGE = '/docs/commerce/test-cc-orders-api/guide/quick-start.html';
+    const REFERENCE_PAGE =
+        '/docs/success/sfdocs/references/markdown-cheatsheet/markdown-cheatsheet.html#how-to-link-between-overviews-guides-and-references';
+
+    let page: GuidePage;
+
+    it('should resolve relative guide link correctly', async () => {
+        page = new GuidePage(UPDATE_ORDER_STATES_PAGE);
+        page.open();
+        await page.waitPageLoad();
+
+        const ordersApiLink = await $('a.internal-link-guide[href*="orders-api-overview"]');
+        await ordersApiLink.waitForDisplayed();
+        const href = await ordersApiLink.getAttribute('href');
+        expect(href).not.toMatch(/\.md(?:\?|#|$)/);
+        expect(href).toContain('orders-api-overview.html');
+    });
+
+    it('should resolve guide linking in same folder correctly', async () => {
+        page = new GuidePage(QUICK_START_PAGE);
+        page.open();
+        await page.waitPageLoad();
+
+        await (await $('>>> doc-heading[hash="see-also"]')).waitForDisplayed();
+
+        const understandTheBasicsLink = await $('=Understand the Basics');
+        await understandTheBasicsLink.waitForDisplayed();
+        const href = await understandTheBasicsLink.getAttribute('href');
+        expect(href).not.toMatch(/\.md(?:\?|#|$)/);
+        expect(href).toContain('understand-the-basics.html');
+    });
+
+    it('should have html link for reference to guide linking', async () => {
+        page = new GuidePage(REFERENCE_PAGE);
+        page.open();
+        await page.waitPageLoad();
+
+        await (
+            await $('>>> doc-heading[hash="how-to-link-between-overviews-guides-and-references"]')
+        ).waitForDisplayed();
+
+        const threeContentTypesLink = await $('=three content types');
+        await threeContentTypesLink.waitForDisplayed();
+        const href = await threeContentTypesLink.getAttribute('href');
+        expect(href).toContain('guide');
+        expect(href).toMatch(/\.html(?:#|$|\?)/);
+    });
+
+    it('should treat external links as external', async () => {
+        page = new GuidePage(REFERENCE_PAGE);
+        page.open();
+        await page.waitPageLoad();
+
+        const externalLinks = await $$('a.external-link-guide');
+        expect(externalLinks.length).toBeGreaterThan(0);
+        for (const link of externalLinks) {
+            expect(await link.getAttribute('target')).toBe('_blank');
+        }
+    });
+});

package/src/shared/specs/layout-tests.ts

@@ -7,7 +7,7 @@ import Page from '../pageobjects/page';
  * @param givenPage : This is the current page for which we need to test chrome.
  */
 
-export default function layoutTest(givenPage: Page, headerTag = 'dx-header') {
+export default function layoutTest(givenPage: Page, headerTag = 'dx-global-header') {
     let page: Page;
     describe('Basic layout testing > ', () => {
         beforeEach(async () => {
@@ -15,10 +15,12 @@ export default function layoutTest(givenPage: Page, headerTag = 'dx-header') {
         });
 
         it('should display header', async () => {
-            const header = await $('hgf-c360contextnav');
+            const header = await $(headerTag);
             await header.waitForDisplayed();
             expect(await header.isDisplayed()).toBeTruthy();
-            expect(await header.getText()).toContain('Developers');
+            if (headerTag === 'dx-global-header') {
+                expect(await header.getText()).toContain('Developers');
+            }
         });
 
         it.skip('should display global search box', async () => {

package/src/shared/specs/reference.test.ts

@@ -9,6 +9,7 @@ describe('API Pages', () => {
         beforeEach(async () => {
             referencePage = new ReferencePage('/docs/commerce/test-cc-orders-api/references');
             referencePage.open();
+            await referencePage.waitForSpecBasedReferencePageLoad();
         });
 
         layoutTest(referencePage, 'doc-header');
@@ -85,6 +86,7 @@ describe('Reference Versioning', () => {
     beforeEach(async () => {
         referencePage = new ReferencePage('/docs/c-cart-apis/references/ref1?meta=Summary');
         referencePage.open();
+        await referencePage.waitForSpecBasedReferencePageLoad();
     });
 
     it('should check for the presence of version picker dropdown', async () => {
@@ -133,7 +135,7 @@ describe('Reference Versioning', () => {
 
         await versionOptions[1].waitForClickable();
         await versionOptions[1].click();
-        await browser.pause(1000);
+        await referencePage.waitForSpecBasedReferencePageLoad();
 
         const apiTitle = await (await $('>>>div.api-title span')).getText();
         const apiVersion = await (await $('>>>p.version span')).getText();
@@ -179,8 +181,10 @@ describe('Reference Versioning', () => {
 
         await referencePage.waitForSpecBasedReferencePageLoad();
         await referencePage.selectVersion();
+        await referencePage.waitForSpecBasedReferencePageLoad();
 
         const container = await $('>>>div.title-area div');
+        await container.waitForDisplayed();
         const apiTitle = await container.getText();
 
         expect(apiTitle).toEqual('createBasket');
@@ -274,6 +278,7 @@ describe('Spec-Based Flexible References', () => {
         await referencePage.waitForSpecBasedReferencePageLoad();
 
         const container = await $('>>>div.title-area div');
+        await container.waitForDisplayed();
         const apiTitle = await container.getText();
 
         expect(apiTitle).toEqual('getBasket');

package/static-dsc-portal-wdio.conf.js

@@ -0,0 +1,49 @@
+/**
+ * WebdriverIO configuration for E2E tests on Static Portal Pages (SSG) on DSC
+ *
+ * Prerequisites:
+ * 1. Build static pages: yarn build:static:portal
+ * 2. Start static server: yarn start:static:portal (runs on port 3000)
+ * 3. Run tests: yarn test:e2e:static:portal
+ */
+const BASE_CONFIG = require('./common-wdio.conf');
+
+exports.config = {
+    ...BASE_CONFIG.config,
+    // Static pages are served on port 3000 by default; override via E2E_BASE_URL env var
+    baseUrl: process.env.E2E_BASE_URL || 'http://localhost:3000',
+
+    // Reuse the same portal specs - static pages have the same URL structure
+    specs: ['./src/portal/specs/**/*.test.ts', './src/shared/specs/*.test.ts'],
+
+    // Exclude tests that require dynamic server features or pages not in static build
+    exclude: [
+        './src/portal/specs/docs.api.test.ts',
+        './src/portal/specs/docs.test.ts',
+        './src/shared/specs/banner.test.ts',
+    ],
+
+    // Output directory for static test results
+    outputDir: './_results_/static-portal',
+
+    // Override reporters to use separate output directories
+    reporters: [
+        'spec',
+        [
+            require('wdio-video-reporter'),
+            {
+                saveAllVideos: false,
+                videoSlowdownMultiplier: 3,
+                outputDir: './_results_/static-portal/videos',
+            },
+        ],
+        [
+            'allure',
+            {
+                outputDir: './_results_/static-portal/allure-raw',
+                disableWebdriverStepsReporting: true,
+                disableWebdriverScreenshotsReporting: false,
+            },
+        ],
+    ],
+};