@salesforcedevs/sfdocs-e2e 1.0.11 → 1.0.12-e2e-topic-version-2

package/package.json

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

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

@@ -40,6 +40,92 @@ describe('Test Sitemap Routes', () => {
         );
     });
 
+    it('lists each docs markdown page once and each spec page without a .html extension', async () => {
+        await HomePage.open('sitemap.xml');
+        const data = await browser.getSitemap(
+            'http://localhost:3000/internal-sitemap-contents-1.xml',
+        );
+
+        // Markdown topics are published with a .html extension.
+        expect(data.body).toContain('<loc>/docs/docs-content-type-example/get-started.html</loc>');
+        expect(data.body).toContain(
+            '<loc>/docs/docs-content-type-example/widget-concepts.html</loc>',
+        );
+        expect(data.body).toContain(
+            '<loc>/docs/docs-content-type-example/beta-bulk-import.html</loc>',
+        );
+
+        // 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/new-sample-api</loc>');
+
+        // Each markdown URL appears exactly once.
+        const occurrences =
+            data.body.split('<loc>/docs/docs-content-type-example/get-started.html</loc>').length -
+            1;
+        expect(occurrences).toBe(1);
+    });
+
+    it('excludes the external-link topic from the docs sitemap', async () => {
+        await HomePage.open('sitemap.xml');
+        const data = await browser.getSitemap(
+            'http://localhost:3000/internal-sitemap-contents-1.xml',
+        );
+
+        // externalLink entries never become routes, so they can't reach the sitemap.
+        expect(data.body).not.toContain('developer.salesforce.com');
+    });
+
+    it('lists the deep-nesting docs project pages and spec in the sitemap', async () => {
+        await HomePage.open('sitemap.xml');
+        const data = await browser.getSitemap(
+            'http://localhost:3000/internal-sitemap-contents-1.xml',
+        );
+
+        expect(data.body).toContain('<loc>/docs/docs-deep-nesting-example/introduction.html</loc>');
+        expect(data.body).toContain('<loc>/docs/docs-deep-nesting-example/install.html</loc>');
+        expect(data.body).toContain('<loc>/docs/docs-deep-nesting-example/workspace.html</loc>');
+        expect(data.body).toContain('<loc>/docs/docs-deep-nesting-example/example-api</loc>');
+    });
+
+    it('lists a localized docs page but omits pages excluded from the ja-jp menu', async () => {
+        await HomePage.open('sitemap.xml');
+        const data = await browser.getSitemap(
+            'http://localhost:3000/internal-sitemap-contents-1.xml',
+        );
+
+        // ja-jp topics that are configured in the ja-jp TOC are legitimately in the sitemap.
+        expect(data.body).toContain(
+            '<loc>/docs/ja-jp/docs-content-type-example/get-started.html</loc>',
+        );
+
+        // englishonly pages are never in the ja-jp menu, so they must not appear under /ja-jp/.
+        expect(data.body).not.toContain(
+            '<loc>/docs/ja-jp/docs-content-type-example/us-compliance-notes.html</loc>',
+        );
+    });
+
+    it('serves the noindex robots metatag on the docs home URL but not on a real topic', async () => {
+        await browser.addCommand('getHtml', async (url: any) => {
+            const data = await got(url);
+            return data;
+        });
+
+        // The project home URL renders the first topic as a landing page with noindex.
+        const home = await browser.getHtml('http://localhost:3000/docs/docs-content-type-example');
+        expect(home.body).toContain('<meta name="robots" content="noindex,nofollow,nosnippet"/>');
+
+        // The same topic requested at its real URL must be indexable.
+        const topic = await browser.getHtml(
+            'http://localhost:3000/docs/docs-content-type-example/get-started.html',
+        );
+        expect(topic.body).not.toContain(
+            '<meta name="robots" content="noindex,nofollow,nosnippet"/>',
+        );
+    });
+
     it('Read Coveo sitemap.xml', async () => {
         await browser.addCommand('getCoveoSitemap', async (url: any) => {
             const data = await got(url, {

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

@@ -33,7 +33,7 @@ class DocsPage extends Page {
     }
 
     private async getTreeTile(treeItem: WebdriverIO.Element): Promise<WebdriverIO.Element> {
-        return treeItem.shadow$('a > dx-tree-tile');
+        return this.getTreeItemTile(treeItem);
     }
 
     private async getTreeItemLabel(treeItem: WebdriverIO.Element): Promise<string> {
@@ -82,6 +82,11 @@ class DocsPage extends Page {
         return (await this.getTreeTile(treeItem)).shadow$('.tile-external-link-icon');
     }
 
+    async getTileAnchor(label: string): Promise<WebdriverIO.Element> {
+        const treeItem = await this.getSidebarTile(label);
+        return (await this.getTreeTile(treeItem)).shadow$('a');
+    }
+
     async getRedocBackLink(): Promise<WebdriverIO.Element> {
         return $('>>>a.redoc-project-back');
     }

package/src/shared/pageobjects/page.ts

@@ -84,6 +84,25 @@ export default class Page {
         return await $('>>>doc-specification-content');
     }
 
+    async getTreeItemTile(treeItem: WebdriverIO.Element): Promise<WebdriverIO.Element> {
+        return treeItem.shadow$('dx-tree-tile');
+    }
+
+    /**
+     * Options render in a single shared overlay, one per picker on the page, hidden until their
+     * own dropdown opens — filtering to visible ones scopes this to whichever just opened.
+     */
+    async getVersionOptions(): Promise<WebdriverIO.Element[]> {
+        const allOptions = await $$('>>>doc-version-picker dx-dropdown-option');
+        const visible: WebdriverIO.Element[] = [];
+        for (const option of allOptions) {
+            if (await option.isDisplayed()) {
+                visible.push(option);
+            }
+        }
+        return visible;
+    }
+
     async waitForSpinnerToDisappear(element: WebdriverIO.Element): Promise<void> {
         await browser.waitUntil(
             async function () {

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

@@ -0,0 +1,196 @@
+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,
+        });
+    }
+
+    // --- Sidebar tree traversal (mirrors docs.page.ts's private helpers, exposed here so
+    // individual rows and their pickers can be located directly) ---
+
+    async getSidebar(): Promise<WebdriverIO.Element> {
+        return (await $('>>>doc-content-layout')).shadow$('div > dx-sidebar-old');
+    }
+
+    async waitForSidebar(): Promise<void> {
+        await (await this.getSidebar()).waitForDisplayed();
+    }
+
+    private async getTreeItemLabel(treeItem: WebdriverIO.Element): Promise<string> {
+        const tile = await this.getTreeItemTile(treeItem);
+        const label = await tile.shadow$('span.tile-label');
+        return (await label.getText()).trim();
+    }
+
+    private async findTreeItemByLabel(
+        treeItem: WebdriverIO.Element,
+        label: string,
+    ): Promise<WebdriverIO.Element | null> {
+        if ((await this.getTreeItemLabel(treeItem)) === label) {
+            return treeItem;
+        }
+
+        const children = await treeItem.shadow$$('dx-tree-item');
+        for (const child of children) {
+            const match = await this.findTreeItemByLabel(child, label);
+            if (match) {
+                return match;
+            }
+        }
+        return null;
+    }
+
+    /** Locates a sidebar tree row (dx-tree-item) by its visible label. */
+    async getSidebarTreeItem(label: string): Promise<WebdriverIO.Element> {
+        const sidebar = await this.getSidebar();
+        const trees = await sidebar.shadow$$('div.container div.sidebar-content dx-tree');
+        for (const tree of trees) {
+            const rootItem = await tree.shadow$('dx-tree-item');
+            const match = await this.findTreeItemByLabel(rootItem, label);
+            if (match) {
+                return match;
+            }
+        }
+        throw new Error(`No sidebar tree item found with label "${label}"`);
+    }
+
+    /** 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`. TODO: unconfirmed whether markdown
+     * topics render this banner at all yet — only the Redoc spec-page banner is confirmed shipped.
+     */
+    async getMarkdownVersionBanner(): Promise<WebdriverIO.Element | null> {
+        const banner = await $('>>>doc-content-layout .doc-phase-wrapper doc-phase');
+        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();
+    }
+
+    /** Opens the picker and clicks the option whose label matches exactly. */
+    async selectVersionByLabel(picker: WebdriverIO.Element, label: string): Promise<void> {
+        await this.openPicker(picker);
+        const options = await this.getVersionOptions();
+        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/contentActionToolbar.test.ts

@@ -1,6 +1,9 @@
+import DocsPage from '../pageobjects/docs.page';
 import GuidePage from '../pageobjects/guide.page';
 import { ReferencePage } from '../pageobjects/reference.page';
 
+const DOCS_MARKDOWN_PATH = '/docs/docs-content-type-example/get-started.html';
+
 const EN_US_GUIDE_PATH = '/docs/service/vscode-maintainer/guide/vscode-overview.html';
 const EN_US_MARKDOWN_REFERENCE_PATH =
     '/docs/commerce/flexible-references/references/shopper-manual-ref/quick-start.html';
@@ -41,6 +44,16 @@ describe('Content action toolbar scenarios', () => {
         await expectToolbarButtons(toolbar);
     });
 
+    it('Markdown docs page should have the toolbar', 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);
+    });
+
     it("Non-markdown reference shouldn't have toolbar", async () => {
         const referencePage = new ReferencePage(NON_MARKDOWN_REFERENCE_PATH);
         referencePage.open();