@salesforcedevs/sfdocs-e2e 1.0.12-fix-redoc-topic-v-1 → 1.0.12-fix-redoc-topic-v-3

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-fix-redoc-topic-v-1",
+  "version": "1.0.12-fix-redoc-topic-v-3",
   "description": "E2E test suite for SFDocs static portal pages (SSG)",
   "license": "ISC",
   "bin": {

package/src/shared/pageobjects/content-action-toolbar.ts

@@ -0,0 +1,105 @@
+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) {
+            // getText() applies the heading's text-transform: uppercase.
+            const heading = String(
+                (await (await group.$(this.MENU_HEADING_SELECTOR)).getProperty('textContent')) ??
+                    '',
+            ).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/page.ts

@@ -111,6 +111,26 @@ export default class Page {
         return (await label.getText()).trim();
     }
 
+    /**
+     * Opens a parent row without navigating. The icon toggles, so skip the click when
+     * the row is already open. WebDriver's click throws on the SVG inside dx-icon, so
+     * click through the DOM instead.
+     */
+    async expandTreeItem(treeItem: WebdriverIO.Element): Promise<void> {
+        const tile = await this.getTreeItemTile(treeItem);
+        const icon = await tile.shadow$('.tile-expand-icon dx-icon');
+        if ((await icon.getAttribute('aria-expanded')) !== 'true') {
+            await browser.execute((expandIcon: { click: () => void }) => {
+                expandIcon.click();
+            }, icon);
+        }
+
+        await browser.waitUntil(async () => (await treeItem.shadow$$('dx-tree-item')).length > 0, {
+            timeout: 5000,
+            timeoutMsg: 'Expected the tree item to expand and render its children',
+        });
+    }
+
     async findTreeItemByLabel(
         treeItem: WebdriverIO.Element,
         label: string,

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

@@ -63,6 +63,23 @@ export default class TopicVersionPage extends Page {
         return wrapper.$('doc-version-picker');
     }
 
+    async openRedocFromSidebar(label: string): Promise<void> {
+        const item = await this.getSidebarTreeItem(label);
+        await item.click();
+        await this.waitForRedocTopicLoad();
+    }
+
+    async selectRedocVersionByLabel(label: string): Promise<void> {
+        const picker = await this.getRedocPicker();
+        await this.selectVersionByLabel(picker!, label);
+        await this.waitForRedocTopicLoad();
+    }
+
+    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
@@ -129,12 +146,17 @@ export default class TopicVersionPage extends Page {
     }
 
     async getOptionLabel(option: WebdriverIO.Element): Promise<string> {
-        const label = await option.shadow$('div>div');
+        const label = await option.shadow$('.option_label');
         return (await label.getText()).trim();
     }
 
     async selectVersionByLabel(picker: WebdriverIO.Element, label: string): Promise<void> {
         await this.openPicker(picker);
+        // The menu fades in. isDisplayed is false while its opacity is still 0.
+        await browser.waitUntil(async () => (await this.getVersionOptions()).length > 0, {
+            timeout: 5000,
+            timeoutMsg: 'Expected the version menu to show its options',
+        });
         const options = await this.getVersionOptions();
         for (const option of options) {
             if ((await this.getOptionLabel(option)) === label) {

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

@@ -1,6 +1,7 @@
 import DocsPage from '../pageobjects/docs.page';
 import GuidePage from '../pageobjects/guide.page';
 import { ReferencePage } from '../pageobjects/reference.page';
+import contentActionToolbar from '../pageobjects/content-action-toolbar';
 
 const DOCS_MARKDOWN_PATH = '/docs/docs-content-type-example/get-started.html';
 
@@ -10,63 +11,154 @@ const EN_US_MARKDOWN_REFERENCE_PATH =
 const NON_MARKDOWN_REFERENCE_PATH = '/docs/test-metamind-oas-api/references/1mkfx9?meta=Summary';
 const NON_EN_US_MARKDOWN_REFERENCE_PATH =
     '/docs/commerce/ja-jp/flex-references-loc/references/manual-ref/commerce-cloud-api-overview.html';
-
-async function expectToolbarButtons(toolbar: WebdriverIO.Element): Promise<void> {
-    const toolbarButtons = await toolbar.shadow$$('dx-button.toolbar-button');
-    expect(toolbarButtons.length).toBe(3);
-
-    const labels = await Promise.all(
-        toolbarButtons.map(async (button) => (await button.getText()).trim()),
-    );
-    expect(labels).toEqual(
-        expect.arrayContaining(['Copy as Markdown', 'View as Markdown', 'Copy URL to Markdown']),
-    );
-}
+const INLINE_MARKDOWN_LABELS = ['Copy as Markdown', 'View as Markdown', 'View llms.txt'];
+const MENU_GROUPS = {
+    'This Page': [
+        'Copy as Markdown',
+        'View as Markdown',
+        'Copy URL to Markdown',
+        'Open in ChatGPT',
+        'Open in Claude',
+        'Open in Perplexity',
+    ],
+    'All Documentation': ['View llms.txt', 'Copy URL to llms.txt'],
+};
+const AI_ASSISTANTS = [
+    { label: 'Open in ChatGPT', host: 'chatgpt.com' },
+    { label: 'Open in Claude', host: 'claude.ai' },
+    { label: 'Open in Perplexity', host: 'www.perplexity.ai' },
+];
+const LLMS_TXT_PATH = '/docs/llms.txt';
+const COPIED_TOOLTIP_LABEL = 'Copied!';
 
 describe('Content action toolbar scenarios', () => {
-    it('Markdown guide should have the toolbar', async () => {
+    it('should show the inline markdown actions when opening a markdown guide', async () => {
         const page = new GuidePage(EN_US_GUIDE_PATH);
         page.open();
         await page.waitPageLoad();
 
-        const toolbar = await $('>>>doc-content-action-toolbar');
-        await toolbar.waitForDisplayed();
-        await expectToolbarButtons(toolbar);
+        const toolbar = await contentActionToolbar.get();
+        expect(await contentActionToolbar.getInlineButtonLabels(toolbar)).toEqual(
+            expect.arrayContaining(INLINE_MARKDOWN_LABELS),
+        );
     });
 
-    it('Markdown reference should have the toolbar', async () => {
+    it('should show the inline markdown actions when opening a markdown reference', async () => {
         const referencePage = new ReferencePage(EN_US_MARKDOWN_REFERENCE_PATH);
         referencePage.open();
         await referencePage.waitForMarkdownBasedReferencePageLoad();
 
-        const toolbar = await $('>>>doc-content-action-toolbar');
-        await toolbar.waitForDisplayed();
-        await expectToolbarButtons(toolbar);
+        const toolbar = await contentActionToolbar.get();
+        expect(await contentActionToolbar.getInlineButtonLabels(toolbar)).toEqual(
+            expect.arrayContaining(INLINE_MARKDOWN_LABELS),
+        );
     });
 
-    it('Markdown docs page should have the toolbar', async () => {
+    it('should show the inline markdown actions when opening a markdown docs page', async () => {
         const page = new DocsPage(DOCS_MARKDOWN_PATH);
         page.open();
         await page.waitPageLoad();
 
-        const toolbar = await $('>>>doc-content-action-toolbar');
-        await toolbar.waitForDisplayed();
-        await expectToolbarButtons(toolbar);
+        const toolbar = await contentActionToolbar.get();
+        expect(await contentActionToolbar.getInlineButtonLabels(toolbar)).toEqual(
+            expect.arrayContaining(INLINE_MARKDOWN_LABELS),
+        );
+    });
+
+    it('should expose the full grouped action set through the More actions menu on a markdown page', async () => {
+        const page = new GuidePage(EN_US_GUIDE_PATH);
+        page.open();
+        await page.waitPageLoad();
+
+        const toolbar = await contentActionToolbar.get();
+        await contentActionToolbar.openMoreActionsMenu(toolbar);
+
+        const labelsByGroup = await contentActionToolbar.getMenuOptionLabelsByGroup(toolbar);
+        expect(Object.keys(labelsByGroup)).toEqual(
+            expect.arrayContaining(Object.keys(MENU_GROUPS)),
+        );
+        for (const [group, expectedLabels] of Object.entries(MENU_GROUPS)) {
+            expect(labelsByGroup[group]).toEqual(expect.arrayContaining(expectedLabels));
+        }
     });
 
-    it("Non-markdown reference shouldn't have toolbar", async () => {
+    AI_ASSISTANTS.forEach(({ label, host }) => {
+        it(`should open ${host} with the page context when selecting ${label}`, async () => {
+            const page = new GuidePage(EN_US_GUIDE_PATH);
+            page.open();
+            await page.waitPageLoad();
+
+            const toolbar = await contentActionToolbar.get();
+            await contentActionToolbar.openMoreActionsMenu(toolbar);
+
+            const url = await contentActionToolbar.getUrlFromNewTab(() =>
+                contentActionToolbar.clickMenuOption(toolbar, label),
+            );
+            expect(url).toContain(host);
+        });
+    });
+
+    it('should open the markdown version of the page in a new tab when selecting View as Markdown', async () => {
+        const page = new GuidePage(EN_US_GUIDE_PATH);
+        page.open();
+        await page.waitPageLoad();
+
+        const toolbar = await contentActionToolbar.get();
+        await contentActionToolbar.openMoreActionsMenu(toolbar);
+
+        const url = await contentActionToolbar.getUrlFromNewTab(() =>
+            contentActionToolbar.clickMenuOption(toolbar, 'View as Markdown'),
+        );
+        expect(url.endsWith('.md')).toBe(true);
+    });
+
+    it('should open the site llms.txt in a new tab when selecting View llms.txt', async () => {
+        const page = new GuidePage(EN_US_GUIDE_PATH);
+        page.open();
+        await page.waitPageLoad();
+
+        const toolbar = await contentActionToolbar.get();
+        await contentActionToolbar.openMoreActionsMenu(toolbar);
+
+        const url = await contentActionToolbar.getUrlFromNewTab(() =>
+            contentActionToolbar.clickMenuOption(toolbar, 'View llms.txt'),
+        );
+        expect(url.endsWith(LLMS_TXT_PATH)).toBe(true);
+    });
+
+    it('should flash the Copied! tooltip when selecting Copy URL to Markdown', async () => {
+        const page = new GuidePage(EN_US_GUIDE_PATH);
+        page.open();
+        await page.waitPageLoad();
+
+        const toolbar = await contentActionToolbar.get();
+        await contentActionToolbar.openMoreActionsMenu(toolbar);
+        await contentActionToolbar.clickMenuOption(toolbar, 'Copy URL to Markdown');
+
+        await browser.waitUntil(
+            async () =>
+                (await contentActionToolbar.getVisibleCopiedTooltipLabel()) ===
+                COPIED_TOOLTIP_LABEL,
+            {
+                timeout: 5000,
+                timeoutMsg: 'Expected the menu tooltip to flash "Copied!"',
+            },
+        );
+    });
+
+    it('should not show the toolbar on a non-markdown reference', async () => {
         const referencePage = new ReferencePage(NON_MARKDOWN_REFERENCE_PATH);
         referencePage.open();
         await referencePage.waitForSpecBasedReferencePageLoad();
 
-        const toolbar = await $('>>>doc-content-action-toolbar');
-        expect(await toolbar.isExisting()).toBeFalsy();
+        expect(await contentActionToolbar.isPresent()).toBeFalsy();
     });
 
-    it("Non en-us locale page shouldn't have toolbar", async () => {
+    it('should not show the toolbar on a non en-us page', async () => {
         const nonEnUsReferencePage = new ReferencePage(NON_EN_US_MARKDOWN_REFERENCE_PATH);
         nonEnUsReferencePage.open();
         await nonEnUsReferencePage.waitForMarkdownBasedReferencePageLoad();
-        expect(await (await $('>>>doc-content-action-toolbar')).isExisting()).toBeFalsy();
+
+        expect(await contentActionToolbar.isPresent()).toBeFalsy();
     });
 });

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

@@ -180,9 +180,7 @@ describe('Topic-level versioning > versioned parent with own content, subtopics
         await page.selectVersionByLabel(picker!, ERRORS_V1_LABEL);
         await page.waitForMarkdownTopicLoad();
 
-        const child = await page.getSidebarTreeItem('Another Spec API');
-        await child.click();
-        await page.waitForRedocTopicLoad();
+        await page.openRedocFromSidebar('Another Spec API');
 
         await page.waitForUrlToContain(`${BASE}/v1/new-sample-api`);
         // v1's spec lacks the `GET /errors/{code}` operation that only v2 has — its absence
@@ -192,16 +190,9 @@ describe('Topic-level versioning > versioned parent with own content, subtopics
     });
 
     it('should show the parent topic version selected on the nested Redoc page after Back', async () => {
-        const child = await page.getSidebarTreeItem('Another Spec API');
-        await child.click();
-        await page.waitForRedocTopicLoad();
-
-        const redocPicker = await page.getRedocPicker();
-        await page.selectVersionByLabel(redocPicker!, ERRORS_V1_LABEL);
-        await page.waitForRedocTopicLoad();
-
-        await (await page.getRedocBackLink()).click();
-        await page.waitForMarkdownTopicLoad();
+        await page.openRedocFromSidebar('Another Spec API');
+        await page.selectRedocVersionByLabel(ERRORS_V1_LABEL);
+        await page.goBackFromRedoc();
 
         await page.waitForUrlToContain(`${BASE}/v1/errors-and-rate-limits.html`);
         const parentPicker = await page.getSidebarPicker('Errors and Rate Limits');
@@ -213,16 +204,9 @@ describe('Topic-level versioning > versioned parent with own content, subtopics
         await page.selectVersionByLabel(picker!, ERRORS_V1_LABEL);
         await page.waitForMarkdownTopicLoad();
 
-        const child = await page.getSidebarTreeItem('Another Spec API');
-        await child.click();
-        await page.waitForRedocTopicLoad();
-
-        const redocPicker = await page.getRedocPicker();
-        await page.selectVersionByLabel(redocPicker!, ERRORS_V2_LABEL);
-        await page.waitForRedocTopicLoad();
-
-        await (await page.getRedocBackLink()).click();
-        await page.waitForMarkdownTopicLoad();
+        await page.openRedocFromSidebar('Another Spec API');
+        await page.selectRedocVersionByLabel(ERRORS_V2_LABEL);
+        await page.goBackFromRedoc();
 
         await page.waitForUrlToEndWith(`${BASE}/errors-and-rate-limits.html`);
         const parentPicker = await page.getSidebarPicker('Errors and Rate Limits');
@@ -235,16 +219,9 @@ describe('Topic-level versioning > versioned parent with own content, subtopics
         await markdownChild.click();
         await page.waitForMarkdownTopicLoad();
 
-        const redocChild = await page.getSidebarTreeItem('Another Spec API');
-        await redocChild.click();
-        await page.waitForRedocTopicLoad();
-
-        const redocPicker = await page.getRedocPicker();
-        await page.selectVersionByLabel(redocPicker!, ERRORS_V1_LABEL);
-        await page.waitForRedocTopicLoad();
-
-        await (await page.getRedocBackLink()).click();
-        await page.waitForMarkdownTopicLoad();
+        await page.openRedocFromSidebar('Another Spec API');
+        await page.selectRedocVersionByLabel(ERRORS_V1_LABEL);
+        await page.goBackFromRedoc();
 
         await page.waitForUrlToContain(`${BASE}/v1/extra-child-a.html`);
         const siblingChild = await page.getSidebarTreeItem('Common Error Codes');
@@ -258,25 +235,22 @@ describe('Topic-level versioning > versioned parent with own content, subtopics
         page.open();
         await page.waitForMarkdownTopicLoad();
 
-        const child = await page.getSidebarTreeItem('Another Spec API');
-        await child.click();
-        await page.waitForRedocTopicLoad();
+        // The spec row is absent until its parent is expanded. Expanding does not
+        // navigate, so Get Started stays the referrer.
+        const parent = await page.getSidebarTreeItem('Errors and Rate Limits');
+        await page.expandTreeItem(parent);
 
-        const redocPicker = await page.getRedocPicker();
-        await page.selectVersionByLabel(redocPicker!, ERRORS_V1_LABEL);
-        await page.waitForRedocTopicLoad();
-
-        await (await page.getRedocBackLink()).click();
-        await page.waitForMarkdownTopicLoad();
+        await page.openRedocFromSidebar('Another Spec API');
+        await page.selectRedocVersionByLabel(ERRORS_V1_LABEL);
+        await page.goBackFromRedoc();
 
         await page.waitForUrlToContain(`${BASE}/get-started.html`);
         expect(await browser.getUrl()).not.toContain('/v1/');
     });
 
     it('should fall back to the project landing page when the Redoc page is opened with no referrer', async () => {
-        // Simulates a fresh direct visit: no stored back target, and `page.open()` (a WebDriver
-        // navigation, not a link click) never sets document.referrer either. Routes through
-        // globalThis since the tsconfig's lib list omits "DOM" (see readSessionVersionSelections).
+        // No stored back target. WebDriver navigation also leaves document.referrer empty.
+        // globalThis: this package's tsconfig lib list omits DOM.
         await browser.execute(() =>
             (globalThis as any).sessionStorage.removeItem('redoc-back-target'),
         );
@@ -285,15 +259,10 @@ describe('Topic-level versioning > versioned parent with own content, subtopics
         page.open();
         await page.waitForRedocTopicLoad();
 
-        const redocPicker = await page.getRedocPicker();
-        await page.selectVersionByLabel(redocPicker!, ERRORS_V1_LABEL);
-        await page.waitForRedocTopicLoad();
-
-        await (await page.getRedocBackLink()).click();
-        await page.waitForMarkdownTopicLoad();
+        await page.selectRedocVersionByLabel(ERRORS_V1_LABEL);
+        await page.goBackFromRedoc();
 
-        // Get Started is the first topic in the TOC, so it's the project's landing page
-        // (headerHref) — and it's unversioned, so no version segment should leak onto it either.
+        // With no back target, Back goes to the first TOC topic. That topic is unversioned.
         await page.waitForUrlToContain(`${BASE}/get-started.html`);
         expect(await browser.getUrl()).not.toContain('/v1/');
     });