@salesforcedevs/sfdocs-e2e 1.0.12-e2e-topic-version-7 → 1.0.12-fix-ver-picker-1

package/common-wdio.conf.js

@@ -89,14 +89,10 @@ const chrome = resolvedChromeDriverVersion ? { version: resolvedChromeDriverVers
 const drivers = {
     // ChromeDriver 115+ is distributed via Chrome for Testing:
     // https://googlechromelabs.github.io/chrome-for-testing/
-    chrome
+    chrome,
+    firefox: { version: '0.35.0' }, // https://github.com/mozilla/geckodriver/releases - 0.30.0+ supports ARM64 Mac
 };
 
-// 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 = {
     //
     // ====================
@@ -192,8 +188,8 @@ exports.config = {
               [
                   'selenium-standalone',
                   {
-                      installArgs: { version: seleniumServerVersion, drivers }, // drivers to install
-                      args: { version: seleniumServerVersion, drivers }, // drivers to use
+                      installArgs: { drivers }, // drivers to install
+                      args: { drivers }, // drivers to use
                   },
               ],
           ],

package/package.json

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

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

@@ -149,9 +149,17 @@ 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 page.getTreeItemLabel(firstChildItem);
+            const firstChildText = await getItemText(firstChildItem);
 
             expect(firstChildText).toBe('Accordion');
         });
@@ -256,10 +264,18 @@ 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 page.getTreeItemLabel(
+            const firstComponentText = await getItemText(
                 (
                     await componentsItem.shadow$$('dx-tree-item')
                 )[0],

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

@@ -56,9 +56,7 @@ describe('Test Sitemap Routes', () => {
         );
 
         // Spec (Redoc) topics are published without an extension.
-        expect(data.body).toContain(
-            '<loc>/docs/docs-content-type-example/widgets-api-reference</loc>',
-        );
+        expect(data.body).toContain('<loc>/docs/docs-content-type-example/sample-api</loc>');
         expect(data.body).toContain('<loc>/docs/docs-content-type-example/new-sample-api</loc>');
 
         // Each markdown URL appears exactly once.

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

@@ -19,23 +19,73 @@ 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> {
+        await treeItem.waitForExist();
+        return treeItem.shadow$('a > dx-tree-tile');
+    }
+
+    private async getTreeItemLabel(treeItem: WebdriverIO.Element): Promise<string> {
+        const treeTile = await this.getTreeTile(treeItem);
+        await treeTile.waitForExist();
+        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> {
-        return this.getSidebarTreeItemByLabel(label);
+        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}"`);
     }
 
     async getTileForwardArrow(label: string): Promise<WebdriverIO.Element> {
         const treeItem = await this.getSidebarTile(label);
-        return (await this.getTreeItemTile(treeItem)).shadow$('.tile-forward-arrow');
+        const treeTile = await this.getTreeTile(treeItem);
+        await treeTile.waitForExist();
+        return treeTile.shadow$('.tile-forward-arrow');
     }
 
     async getTileExternalLinkIcon(label: string): Promise<WebdriverIO.Element> {
         const treeItem = await this.getSidebarTile(label);
-        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.getTreeItemTile(treeItem)).shadow$('a');
+        const treeTile = await this.getTreeTile(treeItem);
+        await treeTile.waitForExist();
+        return treeTile.shadow$('.tile-external-link-icon');
     }
 
     async getRedocBackLink(): Promise<WebdriverIO.Element> {
@@ -69,16 +119,8 @@ 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');
-        const isDisplayed = await Promise.all(options.map((option) => option.isDisplayed()));
-        const visibleOptions = options.filter((_, index) => isDisplayed[index]);
-
-        for (const option of visibleOptions) {
+        for (const option of options) {
             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

@@ -84,69 +84,6 @@ export default class Page {
         return await $('>>>doc-specification-content');
     }
 
-    async getTreeItemTile(treeItem: WebdriverIO.Element): Promise<WebdriverIO.Element> {
-        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 isDisplayed = await Promise.all(allOptions.map((option) => option.isDisplayed()));
-        return allOptions.filter((_, index) => isDisplayed[index]);
-    }
-
     async waitForSpinnerToDisappear(element: WebdriverIO.Element): Promise<void> {
         await browser.waitUntil(
             async function () {

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

@@ -28,6 +28,7 @@ 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/specs/docsContentType.test.ts

@@ -85,7 +85,7 @@ describe('Docs content type', () => {
         await parentTile.click();
         await page.waitPageLoad();
 
-        expect(await browser.getUrl()).toContain('errors-and-rate-limits.html');
+        expect(await browser.getUrl()).toContain('parent-with-refs.html');
         expect(await (await page.getContentHeading()).getText()).toContain(
             'Errors and Rate Limits',
         );
@@ -197,7 +197,7 @@ describe('Docs content type > internal links', () => {
 
 describe('Docs content type > spec (Redoc) topic', () => {
     beforeEach(async () => {
-        page = new DocsPage('/docs/docs-content-type-example/widgets-api-reference');
+        page = new DocsPage('/docs/docs-content-type-example/sample-api');
         page.open();
         await page.waitForRedocLoad();
     });
@@ -218,7 +218,7 @@ describe('Docs content type > spec (Redoc) topic', () => {
 
     it('falls back to the landing topic when the back link is clicked on a directly opened spec', async () => {
         await browser.reloadSession();
-        page = new DocsPage('/docs/docs-content-type-example/widgets-api-reference');
+        page = new DocsPage('/docs/docs-content-type-example/sample-api');
         page.open();
         await page.waitForRedocLoad();
 
@@ -245,7 +245,7 @@ describe('Docs content type > locale picker', () => {
     });
 
     it('shows the language picker on a spec topic of a localized project', async () => {
-        page = new DocsPage('/docs/docs-content-type-example/widgets-api-reference');
+        page = new DocsPage('/docs/docs-content-type-example/sample-api');
         page.open();
         await page.waitForRedocLoad();
 
@@ -256,7 +256,7 @@ describe('Docs content type > locale picker', () => {
     });
 
     it('re-renders the spec in the selected locale when switching language on a spec page', async () => {
-        page = new DocsPage('/docs/docs-content-type-example/widgets-api-reference');
+        page = new DocsPage('/docs/docs-content-type-example/sample-api');
         page.open();
         await page.waitForRedocLoad();
 
@@ -306,7 +306,7 @@ describe('Docs content type > localized (ja-jp) rendering', () => {
     });
 
     it('renders the Redoc view from a ja-jp spec URL', async () => {
-        page = new DocsPage('/docs/ja-jp/docs-content-type-example/widgets-api-reference');
+        page = new DocsPage('/docs/ja-jp/docs-content-type-example/sample-api');
         page.open();
         await page.waitForRedocLoad();
 
@@ -355,7 +355,8 @@ describe('Docs content type > external link', () => {
         await page.waitPageLoad();
         await page.waitForSidebar();
 
-        const anchor = await page.getTileAnchor('Salesforce Developers');
+        const tile = await page.getSidebarTile('Salesforce Developers');
+        const anchor = await tile.shadow$('a');
         expect(await anchor.getAttribute('href')).toContain('https://developer.salesforce.com');
         expect(await anchor.getAttribute('target')).toBe('_blank');
     });

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

@@ -66,24 +66,24 @@ describe('Test Guides page components functionality> ', () => {
 
         expect(sideBarContent.length).toEqual(6);
 
-        const nextStepOption = await (
-            await sideBarContent[3].shadow$('dx-tree-item')
-        ).shadow$('dx-tree-tile');
-
-        expect(nextStepOption.isExisting()).toBeTruthy();
-
-        const installVSCodeOptionTile = await (
-            await sideBarContent[1].shadow$('dx-tree-item')
-        ).shadow$('dx-tree-tile');
-
-        expect(installVSCodeOptionTile.isExisting()).toBeTruthy();
-
-        await (await sideBarContent[1].shadow$('dx-tree-item')).click();
+        const nextStepTreeItem = await sideBarContent[3].shadow$('dx-tree-item');
+        await nextStepTreeItem.waitForExist();
+        const nextStepOption = await nextStepTreeItem.shadow$('dx-tree-tile');
+        await nextStepOption.waitForExist();
+        expect(await nextStepOption.isExisting()).toBeTruthy();
+
+        const installVSCodeTreeItem = await sideBarContent[1].shadow$('dx-tree-item');
+        await installVSCodeTreeItem.waitForExist();
+        const installVSCodeOptionTile = await installVSCodeTreeItem.shadow$('dx-tree-tile');
+        await installVSCodeOptionTile.waitForExist();
+        expect(await installVSCodeOptionTile.isExisting()).toBeTruthy();
+
+        await installVSCodeTreeItem.click();
         await page.waitPageLoad();
 
-        const installVSCodeOption = await (
-            await sideBarContent[1].shadow$('dx-tree-item')
-        ).shadow$$('dx-tree-item');
+        const installVSCodeTreeItemAfterNav = await sideBarContent[1].shadow$('dx-tree-item');
+        await installVSCodeTreeItemAfterNav.waitForExist();
+        const installVSCodeOption = await installVSCodeTreeItemAfterNav.shadow$$('dx-tree-item');
 
         expect(installVSCodeOption.length).toEqual(3);
 
@@ -304,9 +304,15 @@ describe('Search guides', () => {
         await browser.keys('SFRA');
 
         const trees = await sidebar.shadow$$('div.container div.sidebar-content dx-tree');
-        const servicesTree = await (await trees[0].shadow$('dx-tree-item')).shadow$('dx-tree-item');
+        const rootTreeItem = await trees[0].shadow$('dx-tree-item');
+        await rootTreeItem.waitForExist();
+        const servicesTree = await rootTreeItem.shadow$('dx-tree-item');
+        await servicesTree.waitForExist();
         const treeItem = await servicesTree.shadow$('dx-tree-item');
-        const item = await (await treeItem.shadow$('dx-tree-tile')).shadow$('span');
+        await treeItem.waitForExist();
+        const treeTile = await treeItem.shadow$('dx-tree-tile');
+        await treeTile.waitForExist();
+        const item = await treeTile.shadow$('span');
         const itemText = await item.getText();
         expect(itemText).toBe('Find SFRA Tools');
     });
@@ -322,7 +328,10 @@ describe('Search guides', () => {
         await browser.keys('SFRA');
 
         const trees = await (await sidebar).shadow$$('div.container div.sidebar-content dx-tree');
-        const servicesTree = await (await trees[0].shadow$('dx-tree-item')).shadow$('dx-tree-item');
+        const rootTreeItem = await trees[0].shadow$('dx-tree-item');
+        await rootTreeItem.waitForExist();
+        const servicesTree = await rootTreeItem.shadow$('dx-tree-item');
+        await servicesTree.waitForExist();
         const treeItem = await servicesTree.shadow$('dx-tree-item');
         await treeItem.click();
         await page.waitPageLoad();

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

@@ -190,10 +190,13 @@ describe('Redoc API Reference page', () => {
 
                 const secondItem = sideBarContent[1];
                 const treeItem = await secondItem.shadow$('dx-tree-item');
-                const treeTile = await refPage.getTreeItemTile(treeItem);
+                await treeItem.waitForExist();
+                const treeTile = await treeItem.shadow$('a > dx-tree-tile');
+                await treeTile.waitForExist();
                 const arrowIcon = await treeTile.shadow$(
                     'a > div[role="heading"] > div.tile-forward-arrow',
                 );
+                await arrowIcon.waitForExist();
 
                 expect(await arrowIcon.isExisting()).toBeTruthy();
             });

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

@@ -106,9 +106,11 @@ describe('Reference Versioning', () => {
         const versionBtn = await $('>>>.version-picker-button');
         await versionBtn.waitForDisplayed();
         await versionBtn.click();
-        const versionOptions = await referencePage.getVersionOptions();
+        const versionOptions = await $$('>>>doc-version-picker dx-dropdown-option');
 
         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');
     });
@@ -118,19 +120,20 @@ describe('Reference Versioning', () => {
         const searchBox = await dxInput.shadow$('input');
 
         await searchBox.click();
-        await browser.keys('coupon');
-        await browser.pause(1000);
+        await browser.keys('/cart-coupons');
 
         const dxTreeItems = await $$('>>>dx-tree-item');
 
-        await dxTreeItems[2].click();
+        expect(dxTreeItems.length > 2).toBeTruthy();
+
+        await (await dxTreeItems[2]).click();
 
         const versionBtn = await $('>>>.version-picker-button');
 
         await versionBtn.waitForDisplayed();
         await versionBtn.click();
 
-        const versionOptions = await referencePage.getVersionOptions();
+        const versionOptions = await $$('>>>doc-version-picker dx-dropdown-option');
 
         await versionOptions[1].waitForClickable();
         await versionOptions[1].click();
@@ -149,7 +152,9 @@ describe('Reference Versioning', () => {
         await versionPicker.waitForDisplayed();
         await versionPicker.click();
 
-        const versionOptions = await referencePage.getVersionOptions();
+        const versionOptions = await $$('>>>doc-version-picker dx-dropdown-option');
+
+        await versionOptions[1].waitForClickable();
         const selectedVersionText = await (await versionOptions[1].shadow$('div>div')).getText();
 
         await versionOptions[1].click();
@@ -221,11 +226,12 @@ describe('Markdown-Based Flexible References', () => {
         const sidebar = await (await $('>>>doc-content-layout')).shadow$('div > dx-sidebar-old');
         const sideBarContent = await sidebar.shadow$$('div.container div.sidebar-content dx-tree');
         expect(sideBarContent.length).toEqual(1);
-        const tile = await (
-            await sideBarContent[0].shadow$('dx-tree-item')
-        ).shadow$('dx-tree-tile');
-        expect(tile.isExisting()).toBeTruthy();
-        await (await sideBarContent[0].shadow$('dx-tree-item')).click();
+        const treeItem = await sideBarContent[0].shadow$('dx-tree-item');
+        await treeItem.waitForExist();
+        const tile = await treeItem.shadow$('dx-tree-tile');
+        await tile.waitForExist();
+        expect(await tile.isExisting()).toBeTruthy();
+        await treeItem.click();
         await referencePage.waitForMarkdownBasedReferencePageLoad();
         const title = await $('>>>h1');
         const titleText = await title.getText();

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

@@ -1,149 +0,0 @@
-import Page from './page';
-
-/**
- * Page object for topic-level (per-topic) version picker interactions.
- *
- * Two `doc-version-picker` instances exist for a versioned topic:
- *  - the SIDEBAR picker (small variant), rendered as a sibling of `dx-tree-tile` inside the
- *    versioned tree row's own shadow root (`class="tree-item-version-picker"`).
- *  - the REDOC SPEC-PAGE picker (default variant), rendered inside `div.redoc-project-header`
- *    alongside the back-link/spec title. Redoc mounts this header into BOTH `.menu-content` and
- *    `.api-content`, so we always scope through the sidebar's copy (`getRedocProjectHeader`) to
- *    avoid matching the duplicate.
- */
-export default class TopicVersionPage extends Page {
-    async waitForMarkdownTopicLoad(): Promise<void> {
-        await (
-            await $('>>>doc-content-layout')
-        ).waitForDisplayed({ timeout: this.REFERENCE_LOAD_WAIT_TIME });
-    }
-
-    async waitForRedocTopicLoad(): Promise<void> {
-        await $('doc-redoc-reference > .redoc-container').waitForDisplayed({
-            timeout: this.REFERENCE_LOAD_WAIT_TIME,
-        });
-    }
-
-    async getSidebarTreeItem(label: string): Promise<WebdriverIO.Element> {
-        return this.getSidebarTreeItemByLabel(label);
-    }
-
-    /** The sidebar row's own doc-version-picker (small variant), or null if it has none. */
-    async getSidebarPicker(rowLabel: string): Promise<WebdriverIO.Element | null> {
-        const treeItem = await this.getSidebarTreeItem(rowLabel);
-        const picker = await treeItem.shadow$('.tree-item-version-picker');
-        return (await picker.isExisting()) ? picker : null;
-    }
-
-    // --- Redoc spec-page project header (default variant) ---
-
-    private async getRedocSidebar(): Promise<WebdriverIO.Element> {
-        return $('.redoc-wrap > .menu-content');
-    }
-
-    private async getRedocProjectHeader(): Promise<WebdriverIO.Element> {
-        return (await this.getRedocSidebar()).$('div.redoc-project-header');
-    }
-
-    /** The Redoc spec-page's own doc-version-picker, or null if this spec has no versions. */
-    async getRedocPicker(): Promise<WebdriverIO.Element | null> {
-        const header = await this.getRedocProjectHeader();
-        const wrapper = await header.$('.redoc-version-picker');
-        if (!(await wrapper.isExisting())) {
-            return null;
-        }
-        return wrapper.$('doc-version-picker');
-    }
-
-    /**
-     * The dismissible "Newer Version Available" banner shown on a non-latest Redoc spec version.
-     * Reuses the `doc-phase` component, inserted at the top of `.api-content`. Returns null when
-     * absent (latest version, single version, or no versions).
-     */
-    async getRedocVersionBanner(): Promise<WebdriverIO.Element | null> {
-        const banner = await $(
-            'doc-redoc-reference > .redoc-container .api-content .doc-phase-wrapper doc-phase',
-        );
-        return (await banner.isExisting()) ? banner : null;
-    }
-
-    /**
-     * The markdown-topic analog of `getRedocVersionBanner`.
-     */
-    async getMarkdownVersionBanner(): Promise<WebdriverIO.Element | null> {
-        const banner = await $('>>>doc-content-layout doc-phase[slot="version-banner"]');
-        return (await banner.isExisting()) ? banner : null;
-    }
-
-    async getBannerTitle(banner: WebdriverIO.Element): Promise<string> {
-        return (await banner.shadow$('.doc-phase-title')).getText();
-    }
-
-    async getBannerLinkHref(banner: WebdriverIO.Element): Promise<string> {
-        const link = await (await banner.shadow$('.doc-phase-body')).$('a');
-        return link.getAttribute('href');
-    }
-
-    // --- Generic picker interactions (work for either variant) ---
-
-    async getSelectedVersionLabel(picker: WebdriverIO.Element): Promise<string> {
-        const label = await picker.shadow$('p.selected-version-label');
-        return (await label.getText()).trim();
-    }
-
-    async isReadOnly(picker: WebdriverIO.Element): Promise<boolean> {
-        return (await picker.shadow$('p.version-picker-readonly')).isExisting();
-    }
-
-    /** Default (non-small) variant only — the redoc spec-page picker. */
-    async isLatestBadgeShown(picker: WebdriverIO.Element): Promise<boolean> {
-        return (await picker.shadow$('dx-type-badge.latest-badge')).isExisting();
-    }
-
-    async isNotLatestBadgeShown(picker: WebdriverIO.Element): Promise<boolean> {
-        return (await picker.shadow$('dx-type-badge.not-latest-badge')).isExisting();
-    }
-
-    /** Small variant only — the sidebar picker shows a colored dot instead of a badge. */
-    async isLatestDotShown(picker: WebdriverIO.Element): Promise<boolean> {
-        return (await picker.shadow$('span.version-picker-dot-latest')).isExisting();
-    }
-
-    async isNotLatestDotShown(picker: WebdriverIO.Element): Promise<boolean> {
-        return (await picker.shadow$('span.version-picker-dot-not-latest')).isExisting();
-    }
-
-    async openPicker(picker: WebdriverIO.Element): Promise<void> {
-        const trigger = await picker.shadow$('.version-picker-button');
-        await trigger.waitForDisplayed();
-        await trigger.waitForClickable();
-        await trigger.click();
-    }
-
-    async getOptionLabel(option: WebdriverIO.Element): Promise<string> {
-        const label = await option.shadow$('div>div');
-        return (await label.getText()).trim();
-    }
-
-    async selectVersionByLabel(picker: WebdriverIO.Element, label: string): Promise<void> {
-        await this.openPicker(picker);
-        const options = await this.getVersionOptions();
-        for (const option of options) {
-            if ((await this.getOptionLabel(option)) === label) {
-                await option.waitForClickable();
-                await option.click();
-                return;
-            }
-        }
-        throw new Error(`No version option found with label "${label}"`);
-    }
-
-    async readSessionVersionSelections(): Promise<Record<string, string> | null> {
-        // The tsconfig's lib list omits "DOM", so sessionStorage isn't a known global here even
-        // though this callback runs in the browser — route through globalThis to sidestep that.
-        const raw = await browser.execute(() =>
-            (globalThis as any).sessionStorage.getItem('sfdocs-topic-version-selections'),
-        );
-        return raw ? JSON.parse(raw) : null;
-    }
-}

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

@@ -1,412 +0,0 @@
-import { it } from 'mocha';
-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
-// `nd/e2e-topic-version` branch (pinned in example-portal/docsportal.config.js).
-const BASE = '/docs/docs-content-type-example';
-
-let page: TopicVersionPage;
-
-describe('Topic-level versioning > versioned markdown topic', () => {
-    // fixture: OAuth — latest v2 'WI'26' / older v1 'SU'26'.
-    beforeEach(async () => {
-        page = new TopicVersionPage(`${BASE}/oauth.html`);
-        page.open();
-        await page.waitForMarkdownTopicLoad();
-    });
-
-    it('should render the picker and default to the latest version', async () => {
-        const picker = await page.getSidebarPicker('OAuth');
-        expect(picker).not.toBeNull();
-        expect(await page.getSelectedVersionLabel(picker!)).toEqual("WI'26");
-        expect(await page.isLatestDotShown(picker!)).toBeTruthy();
-    });
-
-    it('should list all versions in declared order when the picker is opened', async () => {
-        const picker = await page.getSidebarPicker('OAuth');
-        await page.openPicker(picker!);
-
-        const options = await page.getVersionOptions();
-        expect(options.length).toEqual(2);
-        expect(await page.getOptionLabel(options[0])).toEqual("WI'26");
-        expect(await page.getOptionLabel(options[1])).toEqual("SU'26");
-    });
-
-    it('should switch the page content and URL when a non-latest version is selected', async () => {
-        const picker = await page.getSidebarPicker('OAuth');
-        await page.selectVersionByLabel(picker!, "SU'26");
-        await page.waitForMarkdownTopicLoad();
-
-        expect(await (await $('>>>h1')).getText()).toEqual('OAuth 1.0');
-        expect(await browser.getUrl()).toContain(`${BASE}/v1/oauth.html`);
-    });
-
-    it('should return to the canonical URL when the latest version is reselected', async () => {
-        page = new TopicVersionPage(`${BASE}/v1/oauth.html`);
-        page.open();
-        await page.waitForMarkdownTopicLoad();
-
-        const picker = await page.getSidebarPicker('OAuth');
-        await page.selectVersionByLabel(picker!, "WI'26");
-        await page.waitForMarkdownTopicLoad();
-
-        const url = await browser.getUrl();
-        expect(url.endsWith(`${BASE}/oauth.html`)).toBeTruthy();
-        expect(url).not.toContain('/v2/');
-        expect(await (await $('>>>h1')).getText()).toEqual('OAuth 2.0');
-    });
-
-    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();
-
-        const banner = await page.getMarkdownVersionBanner();
-        expect(banner).not.toBeNull();
-    });
-
-    it('should not show the "Newer Version Available" banner when the version is latest', async () => {
-        const banner = await page.getMarkdownVersionBanner();
-        expect(banner).toBeNull();
-    });
-});
-
-describe('Topic-level versioning > versioned parent with versioned child subtree', () => {
-    // fixture: Client SDKs — latest v2 'WI'26' / older v1 'SU'26'.
-    beforeEach(async () => {
-        page = new TopicVersionPage(`${BASE}/android.html`);
-        page.open();
-        await page.waitForMarkdownTopicLoad();
-    });
-
-    it('should render the picker on the parent and default to the latest version', async () => {
-        const picker = await page.getSidebarPicker('Client SDKs');
-        expect(picker).not.toBeNull();
-        expect(await page.getSelectedVersionLabel(picker!)).toEqual("WI'26");
-    });
-
-    it('should switch the whole child subtree when the parent version changes', async () => {
-        const picker = await page.getSidebarPicker('Client SDKs');
-        await page.selectVersionByLabel(picker!, "SU'26");
-        await page.waitForMarkdownTopicLoad();
-
-        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.
-        const iosItem = await page.getSidebarTreeItem('iOS SDK');
-        const iosTile = await page.getTreeItemTile(iosItem);
-        const iosAnchor = await iosTile.shadow$('a');
-        expect(await iosAnchor.getAttribute('href')).toContain('/v1/ios.html');
-    });
-
-    // TODO: known gap — navigating directly to a different child version URL doesn't sync the
-    // parent's picker or sibling hrefs back to that version; both stay stuck on the version the
-    // page first loaded with. Enable once that reverse sync ships.
-    it.skip('should update the picker and sibling hrefs when navigating directly to a different child version', async () => {
-        page = new TopicVersionPage(`${BASE}/v1/android.html`);
-        page.open();
-        await page.waitForMarkdownTopicLoad();
-
-        page = new TopicVersionPage(`${BASE}/v2/android.html`);
-        page.open();
-        await page.waitForMarkdownTopicLoad();
-
-        const picker = await page.getSidebarPicker('Client SDKs');
-        expect(await page.getSelectedVersionLabel(picker!)).toEqual("WI'26");
-
-        const iosItem = await page.getSidebarTreeItem('iOS SDK');
-        const iosTile = await page.getTreeItemTile(iosItem);
-        const iosAnchor = await iosTile.shadow$('a');
-        const href = await iosAnchor.getAttribute('href');
-        expect(href).toContain('/ios.html');
-        expect(href).not.toContain('/v1/');
-    });
-});
-
-describe('Topic-level versioning > versioned parent with own content, subtopics and a spec subtopic', () => {
-    // fixture: Errors and Rate Limits — latest v2 'SP'26' / older v1 'WI'25'.
-    beforeEach(async () => {
-        page = new TopicVersionPage(`${BASE}/errors-and-rate-limits.html`);
-        page.open();
-        await page.waitForMarkdownTopicLoad();
-    });
-
-    it('should render the picker and default to the latest version', async () => {
-        const picker = await page.getSidebarPicker('Errors and Rate Limits');
-        expect(picker).not.toBeNull();
-        expect(await page.getSelectedVersionLabel(picker!)).toEqual("SP'26");
-    });
-
-    it("should switch the parent's own page content when the version changes", async () => {
-        const picker = await page.getSidebarPicker('Errors and Rate Limits');
-        await page.selectVersionByLabel(picker!, "WI'25");
-        await page.waitForMarkdownTopicLoad();
-
-        expect(await (await $('>>>h1')).getText()).toEqual('Errors and Rate Limits (v1)');
-        expect(await browser.getUrl()).toContain(`${BASE}/v1/errors-and-rate-limits.html`);
-    });
-
-    it('should switch the markdown subtopics when the version changes', async () => {
-        const picker = await page.getSidebarPicker('Errors and Rate Limits');
-        await page.selectVersionByLabel(picker!, "WI'25");
-        await page.waitForMarkdownTopicLoad();
-
-        const child = await page.getSidebarTreeItem('Common Error Codes');
-        await child.click();
-        await page.waitForMarkdownTopicLoad();
-
-        expect(await (await $('>>>h1')).getText()).toEqual('Common Error Codes (v1)');
-        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 () => {
-        // Key cross-type cascade: parent v1 ⇒ the nested spec subtopic is v1 too.
-        const picker = await page.getSidebarPicker('Errors and Rate Limits');
-        await page.selectVersionByLabel(picker!, "WI'25");
-        await page.waitForMarkdownTopicLoad();
-
-        const child = await page.getSidebarTreeItem('Another Spec API');
-        await child.click();
-        await page.waitForRedocTopicLoad();
-
-        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"]');
-        expect(await getErrorCodeOperation.isExisting()).toBeFalsy();
-    });
-
-    // TODO: enable once redoc→parent version-sync ships — the elements already exist, only the
-    // sync behavior is unimplemented.
-    it.skip('should sync the parent topic version when the version is changed on the nested Redoc page', async () => {
-        const child = await page.getSidebarTreeItem('Another Spec API');
-        await child.click();
-        await page.waitForRedocTopicLoad();
-
-        const redocPicker = await page.getRedocPicker();
-        await page.selectVersionByLabel(redocPicker!, "WI'25");
-        await page.waitForRedocTopicLoad();
-
-        page = new TopicVersionPage(`${BASE}/errors-and-rate-limits.html`);
-        page.open();
-        await page.waitForMarkdownTopicLoad();
-
-        const parentPicker = await page.getSidebarPicker('Errors and Rate Limits');
-        expect(await page.getSelectedVersionLabel(parentPicker!)).toEqual("WI'25");
-    });
-});
-
-describe('Topic-level versioning > standalone Redoc reference', () => {
-    // fixture: Widgets API Reference — a spec (forward-arrow) topic, so it never gets a sidebar
-    // picker; the picker lives on the Redoc page's own project header instead.
-    beforeEach(async () => {
-        page = new TopicVersionPage(`${BASE}/widgets-api-reference`);
-        page.open();
-        await page.waitForRedocTopicLoad();
-    });
-
-    it('should render the Redoc version picker and default to the latest version', async () => {
-        const picker = await page.getRedocPicker();
-        expect(picker).not.toBeNull();
-        expect(await page.getSelectedVersionLabel(picker!)).toEqual("SU'26");
-    });
-
-    it('should switch the rendered spec when a different version is selected', async () => {
-        const picker = await page.getRedocPicker();
-        await page.selectVersionByLabel(picker!, "SP'26");
-        await page.waitForRedocTopicLoad();
-
-        expect(await browser.getUrl()).toContain(`${BASE}/v1/widgets-api-reference`);
-        const apiInfo = await $('>>>div.api-info');
-        expect(await apiInfo.getText()).toContain('1.0.0');
-    });
-
-    it('should show the "Newer Version Available" banner when the version is not latest', async () => {
-        page = new TopicVersionPage(`${BASE}/v1/widgets-api-reference`);
-        page.open();
-        await page.waitForRedocTopicLoad();
-
-        const banner = await page.getRedocVersionBanner();
-        expect(banner).not.toBeNull();
-        expect(await page.getBannerTitle(banner!)).toEqual('Newer Version Available');
-        expect(await page.getBannerLinkHref(banner!)).toContain(`${BASE}/widgets-api-reference`);
-    });
-
-    it('should not show the "Newer Version Available" banner when the version is latest', async () => {
-        const banner = await page.getRedocVersionBanner();
-        expect(banner).toBeNull();
-    });
-});
-
-describe('Topic-level versioning > URL resolution (markdown)', () => {
-    it('should serve the latest version at the canonical URL', async () => {
-        page = new TopicVersionPage(`${BASE}/oauth.html`);
-        page.open();
-        await page.waitForMarkdownTopicLoad();
-        expect(await (await $('>>>h1')).getText()).toEqual('OAuth 2.0');
-    });
-
-    it('should serve the latest version at its versioned alias URL', async () => {
-        page = new TopicVersionPage(`${BASE}/v2/oauth.html`);
-        page.open();
-        await page.waitForMarkdownTopicLoad();
-        expect(await (await $('>>>h1')).getText()).toEqual('OAuth 2.0');
-    });
-
-    it('should serve an older version at its versioned URL', async () => {
-        page = new TopicVersionPage(`${BASE}/v1/oauth.html`);
-        page.open();
-        await page.waitForMarkdownTopicLoad();
-        expect(await (await $('>>>h1')).getText()).toEqual('OAuth 1.0');
-    });
-
-    it('should initialize the picker from the URL version', async () => {
-        page = new TopicVersionPage(`${BASE}/v1/oauth.html`);
-        page.open();
-        await page.waitForMarkdownTopicLoad();
-
-        const picker = await page.getSidebarPicker('OAuth');
-        expect(await page.getSelectedVersionLabel(picker!)).toEqual("SU'26");
-    });
-});
-
-describe('Topic-level versioning > URL resolution (spec)', () => {
-    it('should serve the latest spec at the canonical URL', async () => {
-        page = new TopicVersionPage(`${BASE}/widgets-api-reference`);
-        page.open();
-        await page.waitForRedocTopicLoad();
-        expect(await (await $('>>>div.api-info')).getText()).toContain('2.0.0');
-    });
-
-    it('should serve the latest spec at its versioned alias URL', async () => {
-        page = new TopicVersionPage(`${BASE}/v2/widgets-api-reference`);
-        page.open();
-        await page.waitForRedocTopicLoad();
-        expect(await (await $('>>>div.api-info')).getText()).toContain('2.0.0');
-    });
-
-    it('should serve an older spec at its versioned URL', async () => {
-        page = new TopicVersionPage(`${BASE}/v1/widgets-api-reference`);
-        page.open();
-        await page.waitForRedocTopicLoad();
-        expect(await (await $('>>>div.api-info')).getText()).toContain('1.0.0');
-    });
-});
-
-describe('Topic-level versioning > single-version picker (read-only)', () => {
-    // A topic with exactly one authored version still renders a picker, but read-only (no
-    // dropdown) and never with the "Newer Version Available" banner, since a single version is
-    // always the latest by definition.
-    // fixture: Widgets API (Beta) — single version 'Beta'.
-    it('should render a read-only picker with no dropdown when a Redoc spec has a single version', async () => {
-        page = new TopicVersionPage(`${BASE}/widgets-api-beta`);
-        page.open();
-        await page.waitForRedocTopicLoad();
-        const picker = await page.getRedocPicker();
-        expect(await page.isReadOnly(picker!)).toBeTruthy();
-        expect(await page.getRedocVersionBanner()).toBeNull();
-    });
-
-    // fixture: Link Between Topics — already single version ('WI'26'). TODO: enable once
-    // markdown topics render a read-only picker for single-version entries (the markdown
-    // counterpart to the Redoc case above).
-    it.skip('should render a read-only picker with no dropdown when a markdown topic has a single version', async () => {
-        page = new TopicVersionPage(`${BASE}/internal-linking.html`);
-        page.open();
-        await page.waitForMarkdownTopicLoad();
-        const picker = await page.getSidebarPicker('Link Between Topics');
-        expect(await page.isReadOnly(picker!)).toBeTruthy();
-        expect(await page.getMarkdownVersionBanner()).toBeNull();
-    });
-});
-
-describe('Topic-level versioning > topics without a version picker', () => {
-    it('should not render a sidebar picker when the markdown topic is evergreen', async () => {
-        page = new TopicVersionPage(`${BASE}/get-started.html`);
-        page.open();
-        await page.waitForMarkdownTopicLoad();
-
-        const picker = await page.getSidebarPicker('Get Started');
-        expect(picker).toBeNull();
-        expect(await browser.getUrl()).not.toMatch(/\/v\d+\//);
-        expect(await page.getMarkdownVersionBanner()).toBeNull();
-    });
-
-    // fixture: Widgets Status API — plain spec:, no versions: at all.
-    it('should not render a picker when the Redoc spec is evergreen', async () => {
-        page = new TopicVersionPage(`${BASE}/widgets-status-api`);
-        page.open();
-        await page.waitForRedocTopicLoad();
-        expect(await page.getRedocPicker()).toBeNull();
-        expect(await page.getRedocVersionBanner()).toBeNull();
-    });
-
-    it('should show the picker only on versioned rows when the sidebar is mixed', async () => {
-        page = new TopicVersionPage(`${BASE}/get-started.html`);
-        page.open();
-        await page.waitForMarkdownTopicLoad();
-        await page.waitForSidebar();
-
-        expect(await page.getSidebarPicker('OAuth')).not.toBeNull();
-        expect(await page.getSidebarPicker('Errors and Rate Limits')).not.toBeNull();
-        expect(await page.getSidebarPicker('Client SDKs')).not.toBeNull();
-        expect(await page.getSidebarPicker('Get Started')).toBeNull();
-        expect(await page.getSidebarPicker('Widget Concepts')).toBeNull();
-    });
-
-    it('should not leak a version segment when navigating to an evergreen topic', async () => {
-        page = new TopicVersionPage(`${BASE}/v1/oauth.html`);
-        page.open();
-        await page.waitForMarkdownTopicLoad();
-
-        const getStarted = await page.getSidebarTreeItem('Get Started');
-        await getStarted.click();
-        await page.waitForMarkdownTopicLoad();
-
-        expect(await browser.getUrl()).toContain(`${BASE}/get-started.html`);
-        expect(await browser.getUrl()).not.toContain('/v1/');
-    });
-});
-
-describe('Topic-level versioning > persistence on reload', () => {
-    it('should keep the selected version and its content after a refresh', async () => {
-        page = new TopicVersionPage(`${BASE}/oauth.html`);
-        page.open();
-        await page.waitForMarkdownTopicLoad();
-
-        const picker = await page.getSidebarPicker('OAuth');
-        await page.selectVersionByLabel(picker!, "SU'26");
-        await page.waitForMarkdownTopicLoad();
-
-        await browser.refresh();
-        await page.waitForMarkdownTopicLoad();
-
-        const pickerAfterReload = await page.getSidebarPicker('OAuth');
-        expect(await page.getSelectedVersionLabel(pickerAfterReload!)).toEqual("SU'26");
-        expect(await (await $('>>>h1')).getText()).toEqual('OAuth 1.0');
-        expect(await browser.getUrl()).toContain(`${BASE}/v1/oauth.html`);
-
-        const selections = await page.readSessionVersionSelections();
-        expect(selections).not.toBeNull();
-    });
-});
-
-describe('Topic-level versioning > invalid version in URL', () => {
-    it('should return a 404 when the markdown URL has an invalid version', async () => {
-        browser.url(`${BASE}/v999/oauth.html`);
-
-        const errorComponent = await $('dx-error');
-        await errorComponent.waitForDisplayed();
-        expect(await browser.getTitle()).toEqual('404 Error | Salesforce Developers');
-    });
-
-    it('should return a 404 when the spec URL has an invalid version', async () => {
-        browser.url(`${BASE}/v999/widgets-api-reference`);
-
-        const errorComponent = await $('dx-error');
-        await errorComponent.waitForDisplayed();
-        expect(await browser.getTitle()).toEqual('404 Error | Salesforce Developers');
-    });
-});