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

package/package.json

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

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

@@ -15,10 +15,6 @@ class DocsPage extends Page {
         });
     }
 
-    async getContentHeading(): Promise<WebdriverIO.Element> {
-        return (await $('doc-unified-content-layout')).$('div.markdown-content h1');
-    }
-
     async getSidebarTile(label: string): Promise<WebdriverIO.Element> {
         return this.getSidebarTreeItemByLabel(label);
     }

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 });
     }

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

@@ -1,5 +1,8 @@
 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.
  *
@@ -138,11 +141,30 @@ export default class TopicVersionPage extends Page {
         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(() =>
-            (globalThis as any).sessionStorage.getItem('sfdocs-topic-version-selections'),
+        const raw = await browser.execute(
+            (key) => (globalThis as any).sessionStorage.getItem(key),
+            TOPIC_VERSION_SELECTIONS_SESSION_KEY,
         );
         return raw ? JSON.parse(raw) : null;
     }

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

@@ -3,13 +3,23 @@ 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).
+// `mh/topic-level-version` branch (pinned in example-portal/docsportal.config.js).
 const BASE = '/docs/docs-content-type-example';
 
+// Version labels for each fixture's picker, named so a future relabel only needs updating here.
+const OAUTH_V1_LABEL = "SU'26";
+const OAUTH_V2_LABEL = "Winter '26 (API version 65.0) and Spring '26 (API version 66.0)";
+const ERRORS_V2_LABEL = "Summer '26 (API version 67.0)";
+const ERRORS_V1_LABEL = "Spring '26 (API version 66.0)";
+const CLIENT_SDKS_V2_LABEL = "WI'26";
+const CLIENT_SDKS_V1_LABEL = "SU'26";
+const WIDGETS_API_REFERENCE_V2_LABEL = "SU'26";
+const WIDGETS_API_REFERENCE_V1_LABEL = "SP'26";
+
 let page: TopicVersionPage;
 
 describe('Topic-level versioning > versioned markdown topic', () => {
-    // fixture: OAuth — latest v2 'WI'26' / older v1 'SU'26'.
+    // fixture: OAuth — latest is v2 (OAUTH_V2_LABEL), older is v1 (OAUTH_V1_LABEL).
     beforeEach(async () => {
         page = new TopicVersionPage(`${BASE}/oauth.html`);
         page.open();
@@ -19,7 +29,7 @@ describe('Topic-level versioning > versioned markdown topic', () => {
     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.getSelectedVersionLabel(picker!)).toEqual(OAUTH_V2_LABEL);
         expect(await page.isLatestDotShown(picker!)).toBeTruthy();
     });
 
@@ -29,17 +39,17 @@ describe('Topic-level versioning > versioned markdown topic', () => {
 
         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");
+        expect(await page.getOptionLabel(options[0])).toEqual(OAUTH_V2_LABEL);
+        expect(await page.getOptionLabel(options[1])).toEqual(OAUTH_V1_LABEL);
     });
 
     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.selectVersionByLabel(picker!, OAUTH_V1_LABEL);
         await page.waitForMarkdownTopicLoad();
 
-        expect(await (await $('>>>h1')).getText()).toEqual('OAuth 1.0');
-        expect(await browser.getUrl()).toContain(`${BASE}/v1/oauth.html`);
+        expect(await (await page.getContentHeading()).getText()).toEqual('OAuth 1.0');
+        await page.waitForUrlToContain(`${BASE}/v1/oauth.html`);
     });
 
     it('should return to the canonical URL when the latest version is reselected', async () => {
@@ -48,13 +58,14 @@ describe('Topic-level versioning > versioned markdown topic', () => {
         await page.waitForMarkdownTopicLoad();
 
         const picker = await page.getSidebarPicker('OAuth');
-        await page.selectVersionByLabel(picker!, "WI'26");
+        await page.selectVersionByLabel(picker!, OAUTH_V2_LABEL);
         await page.waitForMarkdownTopicLoad();
 
+        await page.waitForUrlToEndWith(`${BASE}/oauth.html`);
         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');
+        expect(await (await page.getContentHeading()).getText()).toEqual('OAuth 2.0');
     });
 
     it('should show the "Newer Version Available" banner when the version is not latest', async () => {
@@ -73,7 +84,7 @@ describe('Topic-level versioning > versioned markdown topic', () => {
 });
 
 describe('Topic-level versioning > versioned parent with versioned child subtree', () => {
-    // fixture: Client SDKs — latest v2 'WI'26' / older v1 'SU'26'.
+    // fixture: Client SDKs — latest is v2 (CLIENT_SDKS_V2_LABEL), older is v1 (CLIENT_SDKS_V1_LABEL).
     beforeEach(async () => {
         page = new TopicVersionPage(`${BASE}/android.html`);
         page.open();
@@ -83,16 +94,16 @@ describe('Topic-level versioning > versioned parent with versioned child subtree
     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");
+        expect(await page.getSelectedVersionLabel(picker!)).toEqual(CLIENT_SDKS_V2_LABEL);
     });
 
     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.selectVersionByLabel(picker!, CLIENT_SDKS_V1_LABEL);
         await page.waitForMarkdownTopicLoad();
 
-        expect(await browser.getUrl()).toContain(`${BASE}/v1/android.html`);
-        expect(await (await $('>>>h1')).getText()).toEqual('Android SDK v1');
+        await page.waitForUrlToContain(`${BASE}/v1/android.html`);
+        expect(await (await page.getContentHeading()).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');
@@ -114,7 +125,7 @@ describe('Topic-level versioning > versioned parent with versioned child subtree
         await page.waitForMarkdownTopicLoad();
 
         const picker = await page.getSidebarPicker('Client SDKs');
-        expect(await page.getSelectedVersionLabel(picker!)).toEqual("WI'26");
+        expect(await page.getSelectedVersionLabel(picker!)).toEqual(CLIENT_SDKS_V2_LABEL);
 
         const iosItem = await page.getSidebarTreeItem('iOS SDK');
         const iosTile = await page.getTreeItemTile(iosItem);
@@ -126,7 +137,7 @@ describe('Topic-level versioning > versioned parent with versioned child subtree
 });
 
 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'.
+    // fixture: Errors and Rate Limits — latest is v2 (ERRORS_V2_LABEL), older is v1 (ERRORS_V1_LABEL).
     beforeEach(async () => {
         page = new TopicVersionPage(`${BASE}/errors-and-rate-limits.html`);
         page.open();
@@ -136,42 +147,44 @@ describe('Topic-level versioning > versioned parent with own content, subtopics
     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");
+        expect(await page.getSelectedVersionLabel(picker!)).toEqual(ERRORS_V2_LABEL);
     });
 
     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.selectVersionByLabel(picker!, ERRORS_V1_LABEL);
         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`);
+        expect(await (await page.getContentHeading()).getText()).toEqual(
+            'Errors and Rate Limits (v1)',
+        );
+        await page.waitForUrlToContain(`${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.selectVersionByLabel(picker!, ERRORS_V1_LABEL);
         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`);
+        expect(await (await page.getContentHeading()).getText()).toEqual('Common Error Codes (v1)');
+        await page.waitForUrlToContain(`${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.selectVersionByLabel(picker!, ERRORS_V1_LABEL);
         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`);
+        await page.waitForUrlToContain(`${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"]');
@@ -186,7 +199,7 @@ describe('Topic-level versioning > versioned parent with own content, subtopics
         await page.waitForRedocTopicLoad();
 
         const redocPicker = await page.getRedocPicker();
-        await page.selectVersionByLabel(redocPicker!, "WI'25");
+        await page.selectVersionByLabel(redocPicker!, ERRORS_V1_LABEL);
         await page.waitForRedocTopicLoad();
 
         page = new TopicVersionPage(`${BASE}/errors-and-rate-limits.html`);
@@ -194,7 +207,7 @@ describe('Topic-level versioning > versioned parent with own content, subtopics
         await page.waitForMarkdownTopicLoad();
 
         const parentPicker = await page.getSidebarPicker('Errors and Rate Limits');
-        expect(await page.getSelectedVersionLabel(parentPicker!)).toEqual("WI'25");
+        expect(await page.getSelectedVersionLabel(parentPicker!)).toEqual(ERRORS_V1_LABEL);
     });
 });
 
@@ -210,15 +223,15 @@ describe('Topic-level versioning > standalone Redoc reference', () => {
     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");
+        expect(await page.getSelectedVersionLabel(picker!)).toEqual(WIDGETS_API_REFERENCE_V2_LABEL);
     });
 
     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.selectVersionByLabel(picker!, WIDGETS_API_REFERENCE_V1_LABEL);
         await page.waitForRedocTopicLoad();
 
-        expect(await browser.getUrl()).toContain(`${BASE}/v1/widgets-api-reference`);
+        await page.waitForUrlToContain(`${BASE}/v1/widgets-api-reference`);
         const apiInfo = await $('>>>div.api-info');
         expect(await apiInfo.getText()).toContain('1.0.0');
     });
@@ -245,21 +258,21 @@ describe('Topic-level versioning > URL resolution (markdown)', () => {
         page = new TopicVersionPage(`${BASE}/oauth.html`);
         page.open();
         await page.waitForMarkdownTopicLoad();
-        expect(await (await $('>>>h1')).getText()).toEqual('OAuth 2.0');
+        expect(await (await page.getContentHeading()).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');
+        expect(await (await page.getContentHeading()).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');
+        expect(await (await page.getContentHeading()).getText()).toEqual('OAuth 1.0');
     });
 
     it('should initialize the picker from the URL version', async () => {
@@ -268,7 +281,7 @@ describe('Topic-level versioning > URL resolution (markdown)', () => {
         await page.waitForMarkdownTopicLoad();
 
         const picker = await page.getSidebarPicker('OAuth');
-        expect(await page.getSelectedVersionLabel(picker!)).toEqual("SU'26");
+        expect(await page.getSelectedVersionLabel(picker!)).toEqual(OAUTH_V1_LABEL);
     });
 });
 
@@ -308,18 +321,6 @@ describe('Topic-level versioning > single-version picker (read-only)', () => {
         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', () => {
@@ -365,7 +366,7 @@ describe('Topic-level versioning > topics without a version picker', () => {
         await getStarted.click();
         await page.waitForMarkdownTopicLoad();
 
-        expect(await browser.getUrl()).toContain(`${BASE}/get-started.html`);
+        await page.waitForUrlToContain(`${BASE}/get-started.html`);
         expect(await browser.getUrl()).not.toContain('/v1/');
     });
 });
@@ -377,19 +378,20 @@ describe('Topic-level versioning > persistence on reload', () => {
         await page.waitForMarkdownTopicLoad();
 
         const picker = await page.getSidebarPicker('OAuth');
-        await page.selectVersionByLabel(picker!, "SU'26");
+        await page.selectVersionByLabel(picker!, OAUTH_V1_LABEL);
         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 page.getSelectedVersionLabel(pickerAfterReload!)).toEqual(OAUTH_V1_LABEL);
+        expect(await (await page.getContentHeading()).getText()).toEqual('OAuth 1.0');
         expect(await browser.getUrl()).toContain(`${BASE}/v1/oauth.html`);
 
         const selections = await page.readSessionVersionSelections();
         expect(selections).not.toBeNull();
+        expect(selections![`${BASE}/oauth.html`]).toEqual('v1');
     });
 });