@salesforcedevs/sfdocs-e2e 1.0.12-e2e-topic-version-5 → 1.0.12-e2e-topic-version-7

package/common-wdio.conf.js

@@ -89,10 +89,14 @@ const chrome = resolvedChromeDriverVersion ? { version: resolvedChromeDriverVers
 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
+    chrome
 };
 
+// selenium-standalone's own default (4.9.0) doesn't support the `-I` driver flag it
+// unconditionally passes on Selenium 4.x, so the server exits immediately on start.
+// Pinning a version that does support it (4.18.1) avoids that crash.
+const seleniumServerVersion = process.env.SELENIUM_VERSION || '4.18.1';
+
 exports.config = {
     //
     // ====================
@@ -188,8 +192,8 @@ exports.config = {
               [
                   'selenium-standalone',
                   {
-                      installArgs: { drivers }, // drivers to install
-                      args: { drivers }, // drivers to use
+                      installArgs: { version: seleniumServerVersion, drivers }, // drivers to install
+                      args: { version: seleniumServerVersion, drivers }, // drivers to use
                   },
               ],
           ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforcedevs/sfdocs-e2e",
-  "version": "1.0.12-e2e-topic-version-5",
+  "version": "1.0.12-e2e-topic-version-7",
   "description": "E2E test suite for SFDocs static portal pages (SSG)",
   "license": "ISC",
   "bin": {

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

@@ -149,17 +149,9 @@ describe('Component Specification', () => {
                 'div.container div.sidebar-content dx-tree',
             );
 
-            const getItemText = async (item: WebdriverIO.Element) => {
-                const link = await item.shadow$('a');
-                const tiles = await link.$$('dx-tree-tile');
-                const tileLink = await tiles[0].shadow$('a.tile.sidebar-item');
-                const label = await tileLink.$('span.tile-label');
-                return (await label.getText()).trim();
-            };
-
             const firstItem = (await sidebarTrees[0].shadow$$('dx-tree-item'))[0];
             const firstChildItem = (await firstItem.shadow$$('dx-tree-item'))[0];
-            const firstChildText = await getItemText(firstChildItem);
+            const firstChildText = await page.getTreeItemLabel(firstChildItem);
 
             expect(firstChildText).toBe('Accordion');
         });
@@ -264,18 +256,10 @@ describe('Component Specification', () => {
                 'div.container div.sidebar-content dx-tree',
             );
 
-            const getItemText = async (item: WebdriverIO.Element) => {
-                const link = await item.shadow$('a');
-                const tiles = await link.$$('dx-tree-tile');
-                const tileLink = await tiles[0].shadow$('a.tile.sidebar-item');
-                const label = await tileLink.$('span.tile-label');
-                return (await label.getText()).trim();
-            };
-
             const auraItem = (await sidebarTrees[1].shadow$$('dx-tree-item'))[0];
             const lightningItem = (await auraItem.shadow$$('dx-tree-item'))[0];
             const componentsItem = (await lightningItem.shadow$$('dx-tree-item'))[0];
-            const firstComponentText = await getItemText(
+            const firstComponentText = await page.getTreeItemLabel(
                 (
                     await componentsItem.shadow$$('dx-tree-item')
                 )[0],

package/src/shared/pageobjects/docs.page.ts

@@ -19,72 +19,23 @@ class DocsPage extends Page {
         return (await $('doc-unified-content-layout')).$('div.markdown-content h1');
     }
 
-    private async getSidebar(): Promise<WebdriverIO.Element> {
-        return (await $('>>>doc-content-layout')).shadow$('div > dx-sidebar-old');
-    }
-
-    async waitForSidebar(): Promise<void> {
-        await (await this.getSidebar()).waitForDisplayed();
-    }
-
-    async getSidebarTrees(): Promise<WebdriverIO.ElementArray> {
-        const sidebar = await this.getSidebar();
-        return sidebar.shadow$$('div.container div.sidebar-content dx-tree');
-    }
-
-    private async getTreeTile(treeItem: WebdriverIO.Element): Promise<WebdriverIO.Element> {
-        return this.getTreeItemTile(treeItem);
-    }
-
-    private async getTreeItemLabel(treeItem: WebdriverIO.Element): Promise<string> {
-        const treeTile = await this.getTreeTile(treeItem);
-        const label = await treeTile.shadow$('span.tile-label');
-        return (await label.getText()).trim();
-    }
-
-    private async findTreeItemByLabel(
-        treeItem: WebdriverIO.Element,
-        label: string,
-    ): Promise<WebdriverIO.Element | null> {
-        if ((await this.getTreeItemLabel(treeItem)) === label) {
-            return treeItem;
-        }
-
-        const children = await treeItem.shadow$$('dx-tree-item');
-        for (const child of children) {
-            const match = await this.findTreeItemByLabel(child, label);
-            if (match) {
-                return match;
-            }
-        }
-        return null;
-    }
-
     async getSidebarTile(label: string): Promise<WebdriverIO.Element> {
-        const trees = await this.getSidebarTrees();
-        for (const tree of trees) {
-            const rootItem = await tree.shadow$('dx-tree-item');
-            const match = await this.findTreeItemByLabel(rootItem, label);
-            if (match) {
-                return match;
-            }
-        }
-        throw new Error(`No sidebar tile found with label "${label}"`);
+        return this.getSidebarTreeItemByLabel(label);
     }
 
     async getTileForwardArrow(label: string): Promise<WebdriverIO.Element> {
         const treeItem = await this.getSidebarTile(label);
-        return (await this.getTreeTile(treeItem)).shadow$('.tile-forward-arrow');
+        return (await this.getTreeItemTile(treeItem)).shadow$('.tile-forward-arrow');
     }
 
     async getTileExternalLinkIcon(label: string): Promise<WebdriverIO.Element> {
         const treeItem = await this.getSidebarTile(label);
-        return (await this.getTreeTile(treeItem)).shadow$('.tile-external-link-icon');
+        return (await this.getTreeItemTile(treeItem)).shadow$('.tile-external-link-icon');
     }
 
     async getTileAnchor(label: string): Promise<WebdriverIO.Element> {
         const treeItem = await this.getSidebarTile(label);
-        return (await this.getTreeTile(treeItem)).shadow$('a');
+        return (await this.getTreeItemTile(treeItem)).shadow$('a');
     }
 
     async getRedocBackLink(): Promise<WebdriverIO.Element> {
@@ -118,8 +69,16 @@ class DocsPage extends Page {
     }
 
     async selectLanguage(displayText: string): Promise<void> {
+        const picker = await this.getLanguagePicker();
+        // A hidden mobile/desktop duplicate of the footer nav can overlap this button at the
+        // same screen coordinates, so a native pointer click risks getting intercepted by it.
+        await browser.execute((el: { click: () => void }) => el.click(), picker);
+
         const options = await $$('>>>dx-dropdown-option');
-        for (const option of options) {
+        const isDisplayed = await Promise.all(options.map((option) => option.isDisplayed()));
+        const visibleOptions = options.filter((_, index) => isDisplayed[index]);
+
+        for (const option of visibleOptions) {
             const link = await option.shadow$('a.option');
             if ((await link.getText()).trim() === displayText) {
                 await browser.execute((el: { click: () => void }) => el.click(), link);

package/src/shared/pageobjects/page.ts

@@ -88,19 +88,63 @@ export default class Page {
         return treeItem.shadow$('dx-tree-tile');
     }
 
+    async getSidebar(): Promise<WebdriverIO.Element> {
+        return (await $('>>>doc-content-layout')).shadow$('div > dx-sidebar-old');
+    }
+
+    async waitForSidebar(): Promise<void> {
+        await (await this.getSidebar()).waitForDisplayed();
+    }
+
+    async getSidebarTrees(): Promise<WebdriverIO.ElementArray> {
+        const sidebar = await this.getSidebar();
+        return sidebar.shadow$$('div.container div.sidebar-content dx-tree');
+    }
+
+    async getTreeItemLabel(treeItem: WebdriverIO.Element): Promise<string> {
+        const tile = await this.getTreeItemTile(treeItem);
+        const label = await tile.shadow$('span.tile-label');
+        return (await label.getText()).trim();
+    }
+
+    async findTreeItemByLabel(
+        treeItem: WebdriverIO.Element,
+        label: string,
+    ): Promise<WebdriverIO.Element | null> {
+        if ((await this.getTreeItemLabel(treeItem)) === label) {
+            return treeItem;
+        }
+
+        const children = await treeItem.shadow$$('dx-tree-item');
+        for (const child of children) {
+            const match = await this.findTreeItemByLabel(child, label);
+            if (match) {
+                return match;
+            }
+        }
+        return null;
+    }
+
+    async getSidebarTreeItemByLabel(label: string): Promise<WebdriverIO.Element> {
+        const trees = await this.getSidebarTrees();
+        for (const tree of trees) {
+            const rootItem = await tree.shadow$('dx-tree-item');
+            const match = await this.findTreeItemByLabel(rootItem, label);
+            if (match) {
+                return match;
+            }
+        }
+        throw new Error(`No sidebar tree item found with label "${label}"`);
+    }
+
     /**
      * Options render in a single shared overlay, one per picker on the page, hidden until their
      * own dropdown opens — filtering to visible ones scopes this to whichever just opened.
      */
     async getVersionOptions(): Promise<WebdriverIO.Element[]> {
         const allOptions = await $$('>>>doc-version-picker dx-dropdown-option');
-        const visible: WebdriverIO.Element[] = [];
-        for (const option of allOptions) {
-            if (await option.isDisplayed()) {
-                visible.push(option);
-            }
-        }
-        return visible;
+        const isDisplayed = await Promise.all(allOptions.map((option) => option.isDisplayed()));
+        return allOptions.filter((_, index) => isDisplayed[index]);
     }
 
     async waitForSpinnerToDisappear(element: WebdriverIO.Element): Promise<void> {

package/src/shared/pageobjects/reference.page.ts

@@ -28,7 +28,6 @@ export class ReferencePage extends Page {
         const versionPicker = await this.getVersionPickerBtn();
         await versionPicker.click();
         const versionOptions = await $$('>>>doc-version-picker dx-dropdown-option');
-        await versionOptions[1].waitForClickable();
         await versionOptions[1].click();
     }
 

package/src/shared/pageobjects/topic-version.page.ts

@@ -24,53 +24,8 @@ export default class TopicVersionPage extends Page {
         });
     }
 
-    // --- Sidebar tree traversal (mirrors docs.page.ts's private helpers, exposed here so
-    // individual rows and their pickers can be located directly) ---
-
-    async getSidebar(): Promise<WebdriverIO.Element> {
-        return (await $('>>>doc-content-layout')).shadow$('div > dx-sidebar-old');
-    }
-
-    async waitForSidebar(): Promise<void> {
-        await (await this.getSidebar()).waitForDisplayed();
-    }
-
-    private async getTreeItemLabel(treeItem: WebdriverIO.Element): Promise<string> {
-        const tile = await this.getTreeItemTile(treeItem);
-        const label = await tile.shadow$('span.tile-label');
-        return (await label.getText()).trim();
-    }
-
-    private async findTreeItemByLabel(
-        treeItem: WebdriverIO.Element,
-        label: string,
-    ): Promise<WebdriverIO.Element | null> {
-        if ((await this.getTreeItemLabel(treeItem)) === label) {
-            return treeItem;
-        }
-
-        const children = await treeItem.shadow$$('dx-tree-item');
-        for (const child of children) {
-            const match = await this.findTreeItemByLabel(child, label);
-            if (match) {
-                return match;
-            }
-        }
-        return null;
-    }
-
-    /** Locates a sidebar tree row (dx-tree-item) by its visible label. */
     async getSidebarTreeItem(label: string): Promise<WebdriverIO.Element> {
-        const sidebar = await this.getSidebar();
-        const trees = await sidebar.shadow$$('div.container div.sidebar-content dx-tree');
-        for (const tree of trees) {
-            const rootItem = await tree.shadow$('dx-tree-item');
-            const match = await this.findTreeItemByLabel(rootItem, label);
-            if (match) {
-                return match;
-            }
-        }
-        throw new Error(`No sidebar tree item found with label "${label}"`);
+        return this.getSidebarTreeItemByLabel(label);
     }
 
     /** The sidebar row's own doc-version-picker (small variant), or null if it has none. */
@@ -113,11 +68,10 @@ export default class TopicVersionPage extends Page {
     }
 
     /**
-     * The markdown-topic analog of `getRedocVersionBanner`. TODO: unconfirmed whether markdown
-     * topics render this banner at all yet — only the Redoc spec-page banner is confirmed shipped.
+     * The markdown-topic analog of `getRedocVersionBanner`.
      */
     async getMarkdownVersionBanner(): Promise<WebdriverIO.Element | null> {
-        const banner = await $('>>>doc-content-layout .doc-phase-wrapper doc-phase');
+        const banner = await $('>>>doc-content-layout doc-phase[slot="version-banner"]');
         return (await banner.isExisting()) ? banner : null;
     }
 
@@ -171,7 +125,6 @@ export default class TopicVersionPage extends Page {
         return (await label.getText()).trim();
     }
 
-    /** Opens the picker and clicks the option whose label matches exactly. */
     async selectVersionByLabel(picker: WebdriverIO.Element, label: string): Promise<void> {
         await this.openPicker(picker);
         const options = await this.getVersionOptions();

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

@@ -187,9 +187,11 @@ describe('Redoc API Reference page', () => {
 
             it('should show arrow button after OAS reference titles', async () => {
                 const sideBarContent = await refPage.getSidebarItems();
-                const treeItem = await sideBarContent[1].shadow$('dx-tree-item');
-                const tile = await refPage.getTreeItemTile(treeItem);
-                const arrowIcon = await tile.shadow$(
+
+                const secondItem = sideBarContent[1];
+                const treeItem = await secondItem.shadow$('dx-tree-item');
+                const treeTile = await refPage.getTreeItemTile(treeItem);
+                const arrowIcon = await treeTile.shadow$(
                     'a > div[role="heading"] > div.tile-forward-arrow',
                 );
 

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

@@ -106,11 +106,9 @@ describe('Reference Versioning', () => {
         const versionBtn = await $('>>>.version-picker-button');
         await versionBtn.waitForDisplayed();
         await versionBtn.click();
-        const versionOptions = await $$('>>>doc-version-picker dx-dropdown-option');
+        const versionOptions = await referencePage.getVersionOptions();
 
         expect(versionOptions.length).toEqual(2);
-        await versionOptions[0].waitForClickable();
-        await versionOptions[1].waitForClickable();
         expect(await (await versionOptions[0].shadow$('div>div')).getText()).toEqual('0.1.3');
         expect(await (await versionOptions[1].shadow$('div>div')).getText()).toEqual('0.1.2');
     });
@@ -120,34 +118,26 @@ describe('Reference Versioning', () => {
         const searchBox = await dxInput.shadow$('input');
 
         await searchBox.click();
-        await browser.keys('/cart-coupons');
+        await browser.keys('coupon');
+        await browser.pause(1000);
 
         const dxTreeItems = await $$('>>>dx-tree-item');
 
-        expect(dxTreeItems.length > 2).toBeTruthy();
-
-        await (await dxTreeItems[2]).click();
+        await dxTreeItems[2].click();
 
         const versionBtn = await $('>>>.version-picker-button');
 
         await versionBtn.waitForDisplayed();
         await versionBtn.click();
 
-        const versionOptions = await $$('>>>doc-version-picker dx-dropdown-option');
+        const versionOptions = await referencePage.getVersionOptions();
 
         await versionOptions[1].waitForClickable();
         await versionOptions[1].click();
         await referencePage.waitForSpecBasedReferencePageLoad();
 
-        // The outer container can display before Redoc finishes populating its content, so wait
-        // for each element directly rather than reading them immediately.
-        const apiTitleElement = await $('>>>div.api-title span');
-        await apiTitleElement.waitForDisplayed();
-        const apiVersionElement = await $('>>>p.version span');
-        await apiVersionElement.waitForDisplayed();
-
-        const apiTitle = await apiTitleElement.getText();
-        const apiVersion = await apiVersionElement.getText();
+        const apiTitle = await (await $('>>>div.api-title span')).getText();
+        const apiVersion = await (await $('>>>p.version span')).getText();
 
         expect(apiTitle).toEqual('Salesforce Connect API');
         expect(apiVersion).toEqual('53.0');
@@ -159,9 +149,7 @@ describe('Reference Versioning', () => {
         await versionPicker.waitForDisplayed();
         await versionPicker.click();
 
-        const versionOptions = await $$('>>>doc-version-picker dx-dropdown-option');
-
-        await versionOptions[1].waitForClickable();
+        const versionOptions = await referencePage.getVersionOptions();
         const selectedVersionText = await (await versionOptions[1].shadow$('div>div')).getText();
 
         await versionOptions[1].click();

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

@@ -3,7 +3,7 @@ import TopicVersionPage from '../pageobjects/topic-version.page';
 
 // Fixtures live in the `docs-content-type-example` project, kept in sync between this monorepo's
 // local `packages/example-repository` and the remote `salesforcedocs/example-repository`'s
-// `mh/topic-level-version` branch.
+// `nd/e2e-topic-version` branch (pinned in example-portal/docsportal.config.js).
 const BASE = '/docs/docs-content-type-example';
 
 let page: TopicVersionPage;
@@ -39,10 +39,7 @@ describe('Topic-level versioning > versioned markdown topic', () => {
         await page.waitForMarkdownTopicLoad();
 
         expect(await (await $('>>>h1')).getText()).toEqual('OAuth 1.0');
-        await browser.waitUntil(
-            async () => (await browser.getUrl()).includes(`${BASE}/v1/oauth.html`),
-            { timeoutMsg: 'expected URL to contain /v1/oauth.html' },
-        );
+        expect(await browser.getUrl()).toContain(`${BASE}/v1/oauth.html`);
     });
 
     it('should return to the canonical URL when the latest version is reselected', async () => {
@@ -60,9 +57,7 @@ describe('Topic-level versioning > versioned markdown topic', () => {
         expect(await (await $('>>>h1')).getText()).toEqual('OAuth 2.0');
     });
 
-    // TODO: unconfirmed whether markdown topics render this banner at all yet (only Redoc spec
-    // pages are confirmed to). Enable once verified.
-    it.skip('should show the "Newer Version Available" banner when the version is not latest', async () => {
+    it('should show the "Newer Version Available" banner when the version is not latest', async () => {
         page = new TopicVersionPage(`${BASE}/v1/oauth.html`);
         page.open();
         await page.waitForMarkdownTopicLoad();
@@ -96,10 +91,7 @@ describe('Topic-level versioning > versioned parent with versioned child subtree
         await page.selectVersionByLabel(picker!, "SU'26");
         await page.waitForMarkdownTopicLoad();
 
-        await browser.waitUntil(
-            async () => (await browser.getUrl()).includes(`${BASE}/v1/android.html`),
-            { timeoutMsg: 'expected URL to contain /v1/android.html' },
-        );
+        expect(await browser.getUrl()).toContain(`${BASE}/v1/android.html`);
         expect(await (await $('>>>h1')).getText()).toEqual('Android SDK v1');
 
         // Sibling child (iOS SDK) should also have moved to the v1 URL, not just this one.
@@ -117,7 +109,7 @@ describe('Topic-level versioning > versioned parent with versioned child subtree
         page.open();
         await page.waitForMarkdownTopicLoad();
 
-        page = new TopicVersionPage(`${BASE}/android.html`);
+        page = new TopicVersionPage(`${BASE}/v2/android.html`);
         page.open();
         await page.waitForMarkdownTopicLoad();
 
@@ -153,10 +145,7 @@ describe('Topic-level versioning > versioned parent with own content, subtopics
         await page.waitForMarkdownTopicLoad();
 
         expect(await (await $('>>>h1')).getText()).toEqual('Errors and Rate Limits (v1)');
-        await browser.waitUntil(
-            async () => (await browser.getUrl()).includes(`${BASE}/v1/errors-and-rate-limits.html`),
-            { timeoutMsg: 'expected URL to contain /v1/errors-and-rate-limits.html' },
-        );
+        expect(await browser.getUrl()).toContain(`${BASE}/v1/errors-and-rate-limits.html`);
     });
 
     it('should switch the markdown subtopics when the version changes', async () => {
@@ -169,10 +158,7 @@ describe('Topic-level versioning > versioned parent with own content, subtopics
         await page.waitForMarkdownTopicLoad();
 
         expect(await (await $('>>>h1')).getText()).toEqual('Common Error Codes (v1)');
-        await browser.waitUntil(
-            async () => (await browser.getUrl()).includes(`${BASE}/v1/extra-child-a.html`),
-            { timeoutMsg: 'expected URL to contain /v1/extra-child-a.html' },
-        );
+        expect(await browser.getUrl()).toContain(`${BASE}/v1/extra-child-a.html`);
     });
 
     it('should switch the spec (Redoc) subtopic to the matching version when the version changes', async () => {
@@ -185,10 +171,7 @@ describe('Topic-level versioning > versioned parent with own content, subtopics
         await child.click();
         await page.waitForRedocTopicLoad();
 
-        await browser.waitUntil(
-            async () => (await browser.getUrl()).includes(`${BASE}/v1/new-sample-api`),
-            { timeoutMsg: 'expected URL to contain /v1/new-sample-api' },
-        );
+        expect(await browser.getUrl()).toContain(`${BASE}/v1/new-sample-api`);
         // v1's spec lacks the `GET /errors/{code}` operation that only v2 has — its absence
         // confirms the v1 spec asset loaded, since both versions share the same spec title.
         const getErrorCodeOperation = await $('a[href*="operation/getErrorCode"]');
@@ -235,10 +218,7 @@ describe('Topic-level versioning > standalone Redoc reference', () => {
         await page.selectVersionByLabel(picker!, "SP'26");
         await page.waitForRedocTopicLoad();
 
-        await browser.waitUntil(
-            async () => (await browser.getUrl()).includes(`${BASE}/v1/widgets-api-reference`),
-            { timeoutMsg: 'expected URL to contain /v1/widgets-api-reference' },
-        );
+        expect(await browser.getUrl()).toContain(`${BASE}/v1/widgets-api-reference`);
         const apiInfo = await $('>>>div.api-info');
         expect(await apiInfo.getText()).toContain('1.0.0');
     });