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

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

@@ -0,0 +1,432 @@
+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
+// `mh/topic-level-version` branch.
+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');
+        await browser.waitUntil(
+            async () => (await browser.getUrl()).includes(`${BASE}/v1/oauth.html`),
+            { timeoutMsg: 'expected URL to contain /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');
+    });
+
+    // TODO: unconfirmed whether markdown topics render this banner at all yet (only Redoc spec
+    // pages are confirmed to). Enable once verified.
+    it.skip('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();
+
+        await browser.waitUntil(
+            async () => (await browser.getUrl()).includes(`${BASE}/v1/android.html`),
+            { timeoutMsg: 'expected URL to contain /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}/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)');
+        await browser.waitUntil(
+            async () => (await browser.getUrl()).includes(`${BASE}/v1/errors-and-rate-limits.html`),
+            { timeoutMsg: 'expected URL to contain /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)');
+        await browser.waitUntil(
+            async () => (await browser.getUrl()).includes(`${BASE}/v1/extra-child-a.html`),
+            { timeoutMsg: 'expected URL to contain /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();
+
+        await browser.waitUntil(
+            async () => (await browser.getUrl()).includes(`${BASE}/v1/new-sample-api`),
+            { timeoutMsg: 'expected URL to contain /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();
+
+        await browser.waitUntil(
+            async () => (await browser.getUrl()).includes(`${BASE}/v1/widgets-api-reference`),
+            { timeoutMsg: 'expected URL to contain /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');
+    });
+});