@salesforcedevs/sfdocs-e2e 1.0.12-fix-ver-picker-1 → 1.0.12-fix-redoc-topic-v-2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforcedevs/sfdocs-e2e",
-  "version": "1.0.12-fix-ver-picker-1",
+  "version": "1.0.12-fix-redoc-topic-v-2",
   "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/content-repo/specs/sitemap.test.ts

@@ -56,7 +56,9 @@ describe('Test Sitemap Routes', () => {
         );
 
         // Spec (Redoc) topics are published without an extension.
-        expect(data.body).toContain('<loc>/docs/docs-content-type-example/sample-api</loc>');
+        expect(data.body).toContain(
+            '<loc>/docs/docs-content-type-example/widgets-api-reference</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/content-action-toolbar.ts

@@ -0,0 +1,101 @@
+class ContentActionToolbar {
+    HOST_SELECTOR = 'doc-content-action-toolbar';
+    INLINE_BUTTON_SELECTOR = 'dx-button.toolbar-button';
+    MENU_TRIGGER_SELECTOR = 'dx-button.menu-trigger';
+    MENU_SELECTOR = 'dx-dropdown.toolbar-menu';
+    MENU_GROUP_SELECTOR = 'div.menu_option';
+    MENU_HEADING_SELECTOR = 'span.menu_heading';
+    MENU_OPTION_SELECTOR = 'dx-dropdown-option';
+    OPTION_LABEL_SELECTOR = 'div.option_label';
+    COPIED_TOOLTIP_SELECTOR = '[role="tooltip"].is-visible';
+
+    async get(): Promise<WebdriverIO.Element> {
+        const toolbar = await $(`>>>${this.HOST_SELECTOR}`);
+        await toolbar.waitForDisplayed();
+        return toolbar;
+    }
+
+    async isPresent(): Promise<boolean> {
+        return (await $(`>>>${this.HOST_SELECTOR}`)).isExisting();
+    }
+
+    async getInlineButtonLabels(toolbar: WebdriverIO.Element): Promise<string[]> {
+        const inlineButtons = await toolbar.shadow$$(this.INLINE_BUTTON_SELECTOR);
+        return Promise.all(inlineButtons.map(async (button) => (await button.getText()).trim()));
+    }
+
+    async openMoreActionsMenu(toolbar: WebdriverIO.Element): Promise<void> {
+        const trigger = await toolbar.shadow$(this.MENU_TRIGGER_SELECTOR);
+        await trigger.waitForClickable();
+        await trigger.click();
+    }
+
+    async getMenuOptionLabelsByGroup(
+        toolbar: WebdriverIO.Element,
+    ): Promise<Record<string, string[]>> {
+        const dropdown = await toolbar.shadow$(this.MENU_SELECTOR);
+        const groupContainers = await dropdown.shadow$$(this.MENU_GROUP_SELECTOR);
+
+        const labelsByGroup: Record<string, string[]> = {};
+        for (const group of groupContainers) {
+            const heading = (await (await group.$(this.MENU_HEADING_SELECTOR)).getText()).trim();
+            const options = await group.$$(this.MENU_OPTION_SELECTOR);
+            labelsByGroup[heading] = await Promise.all(
+                options.map(async (option) =>
+                    (await (await option.shadow$(this.OPTION_LABEL_SELECTOR)).getText()).trim(),
+                ),
+            );
+        }
+        return labelsByGroup;
+    }
+
+    async clickMenuOption(toolbar: WebdriverIO.Element, label: string): Promise<void> {
+        const dropdown = await toolbar.shadow$(this.MENU_SELECTOR);
+        const options = await dropdown.shadow$$(this.MENU_OPTION_SELECTOR);
+        for (const option of options) {
+            const optionLabel = (
+                await (await option.shadow$(this.OPTION_LABEL_SELECTOR)).getText()
+            ).trim();
+            if (optionLabel === label) {
+                await option.click();
+                return;
+            }
+        }
+        throw new Error(`Menu option "${label}" not found`);
+    }
+
+    async getUrlFromNewTab(action: () => Promise<void>): Promise<string> {
+        const originalHandle = await browser.getWindowHandle();
+        const handlesBefore = await browser.getWindowHandles();
+
+        await action();
+
+        await browser.waitUntil(
+            async (): Promise<boolean> =>
+                (await browser.getWindowHandles()).length > handlesBefore.length,
+            {
+                timeout: 10000,
+                timeoutMsg: 'Expected a new browser tab to open',
+            },
+        );
+
+        const handlesAfter = await browser.getWindowHandles();
+        const newHandle = handlesAfter.find((handle) => !handlesBefore.includes(handle));
+        if (!newHandle) {
+            throw new Error('New browser tab opened but its handle could not be resolved');
+        }
+        await browser.switchToWindow(newHandle);
+        const url = await browser.getUrl();
+
+        await browser.closeWindow();
+        await browser.switchToWindow(originalHandle);
+        return url;
+    }
+
+    async getVisibleCopiedTooltipLabel(): Promise<string> {
+        const tooltip = await $(`>>>${this.COPIED_TOOLTIP_SELECTOR}`);
+        return (await tooltip.getAttribute('aria-label'))?.trim() ?? '';
+    }
+}
+
+export default new ContentActionToolbar();

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

@@ -15,77 +15,23 @@ class DocsPage extends Page {
         });
     }
 
-    async getContentHeading(): Promise<WebdriverIO.Element> {
-        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> {
-        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);
-        const treeTile = await this.getTreeTile(treeItem);
-        await treeTile.waitForExist();
-        return treeTile.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);
-        const treeTile = await this.getTreeTile(treeItem);
-        await treeTile.waitForExist();
-        return treeTile.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.getTreeItemTile(treeItem)).shadow$('a');
     }
 
     async getRedocBackLink(): Promise<WebdriverIO.Element> {
@@ -119,8 +65,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

@@ -58,6 +58,10 @@ export default class Page {
         ).waitForDisplayed({ timeout: this.REFERENCE_LOAD_WAIT_TIME });
     }
 
+    async getContentHeading(): Promise<WebdriverIO.Element> {
+        return (await $('doc-unified-content-layout')).$('div.markdown-content h1');
+    }
+
     async waitForGuidePageLoad(): Promise<void> {
         await $('doc-content-layout').waitForDisplayed({ timeout: 5000 });
     }
@@ -84,6 +88,80 @@ 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();
+    }
+
+    /**
+     * Toggles a parent tree item open without navigating — the expand icon's own click handler
+     * calls preventDefault/stopPropagation, unlike the tile's main link. Needed to reach a child
+     * row (e.g. a nested Redoc spec) that isn't rendered in the DOM until its parent is expanded.
+     */
+    async expandTreeItem(treeItem: WebdriverIO.Element): Promise<void> {
+        const tile = await this.getTreeItemTile(treeItem);
+        const icon = await tile.shadow$('.tile-expand-icon dx-icon');
+        await icon.click();
+    }
+
+    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,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

@@ -0,0 +1,196 @@
+import Page from './page';
+
+/** Must match the sessionStorage key the doc-version-picker component writes to. */
+const TOPIC_VERSION_SELECTIONS_SESSION_KEY = 'sfdocs-topic-version-selections';
+
+/**
+ * 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');
+    }
+
+    /** Back link in the menu header, not the duplicate inside api-content. */
+    async getRedocBackLink(): Promise<WebdriverIO.Element> {
+        return (await this.getRedocProjectHeader()).$('a.redoc-project-back');
+    }
+
+    /** 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');
+    }
+
+    /** Clicks a sidebar tree item and waits for the Redoc page it opens to load. */
+    async openRedocFromSidebar(label: string): Promise<void> {
+        const item = await this.getSidebarTreeItem(label);
+        await item.click();
+        await this.waitForRedocTopicLoad();
+    }
+
+    /** Selects a version on the Redoc page's own picker and waits for the new spec to load. */
+    async selectRedocVersionByLabel(label: string): Promise<void> {
+        const picker = await this.getRedocPicker();
+        await this.selectVersionByLabel(picker!, label);
+        await this.waitForRedocTopicLoad();
+    }
+
+    /** Clicks the Redoc back link and waits for the markdown page it returns to load. */
+    async goBackFromRedoc(): Promise<void> {
+        await (await this.getRedocBackLink()).click();
+        await this.waitForMarkdownTopicLoad();
+    }
+
+    /**
+     * 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}"`);
+    }
+
+    private async waitForUrlCondition(
+        description: string,
+        predicate: (url: string) => boolean,
+    ): Promise<void> {
+        await browser.waitUntil(async () => predicate(await browser.getUrl()), {
+            timeout: 15000,
+            timeoutMsg: `expected URL to ${description}`,
+        });
+    }
+
+    async waitForUrlToContain(path: string): Promise<void> {
+        await this.waitForUrlCondition(`contain ${path}`, (url) => url.includes(path));
+    }
+
+    async waitForUrlToEndWith(path: string): Promise<void> {
+        await this.waitForUrlCondition(`end with ${path}`, (url) => url.endsWith(path));
+    }
+
+    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(
+            (key) => (globalThis as any).sessionStorage.getItem(key),
+            TOPIC_VERSION_SELECTIONS_SESSION_KEY,
+        );
+        return raw ? JSON.parse(raw) : null;
+    }
+}