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

package/package.json

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

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

@@ -40,6 +40,90 @@ 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/sample-api</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,10 @@ export default class Page {
         return await $('>>>doc-specification-content');
     }
 
+    async getTreeItemTile(treeItem: WebdriverIO.Element): Promise<WebdriverIO.Element> {
+        return treeItem.shadow$('dx-tree-tile');
+    }
+
     async waitForSpinnerToDisappear(element: WebdriverIO.Element): Promise<void> {
         await browser.waitUntil(
             async function () {

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

@@ -0,0 +1,201 @@
+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();
+    }
+
+    /** Dropdown options render in a single shared overlay, so this is a global (unscoped) query. */
+    async getVersionOptions(): Promise<WebdriverIO.ElementArray> {
+        return $$('>>>doc-version-picker dx-dropdown-option');
+    }
+
+    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();

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

@@ -290,6 +290,292 @@ describe('Docs content type > locale picker', () => {
     });
 });
 
+describe('Docs content type > localized (ja-jp) rendering', () => {
+    it('renders the Japanese body and sidebar on a ja-jp markdown topic', async () => {
+        page = new DocsPage('/docs/ja-jp/docs-content-type-example/get-started.html');
+        page.open();
+        await page.waitPageLoad();
+        await page.waitForSidebar();
+
+        expect(await (await page.getContentHeading()).getText()).toContain(
+            'ウィジェット サービスを始める',
+        );
+        // Sidebar tiles are localized — the Japanese "Widget Concepts" label resolves.
+        const tile = await page.getSidebarTile('ウィジェットの概念');
+        expect(await tile.isExisting()).toBe(true);
+    });
+
+    it('renders the Redoc view from a ja-jp spec URL', async () => {
+        page = new DocsPage('/docs/ja-jp/docs-content-type-example/sample-api');
+        page.open();
+        await page.waitForRedocLoad();
+
+        expect(await browser.getUrl()).toContain('/ja-jp/');
+        expect(await (await page.getRedocApiTitle()).getText()).not.toBe('');
+    });
+});
+
+describe('Docs content type > englishonly filter', () => {
+    it('serves the englishonly topic in English', async () => {
+        page = new DocsPage('/docs/docs-content-type-example/us-compliance-notes.html');
+        page.open();
+        await page.waitPageLoad();
+
+        expect(await (await page.getContentHeading()).getText()).toContain('US Compliance Notes');
+    });
+});
+
+describe('Docs content type > language picker round-trip', () => {
+    it('switches a markdown topic between English and Japanese and back', async () => {
+        page = new DocsPage('/docs/docs-content-type-example/get-started.html');
+        page.open();
+        await page.waitPageLoad();
+        await page.waitForSidebar();
+
+        await page.selectLanguage('日本語');
+        await page.waitPageLoad();
+        expect(await browser.getUrl()).toContain('/ja-jp/');
+        expect(await browser.getUrl()).toContain('get-started.html');
+        expect(await (await page.getContentHeading()).getText()).toContain(
+            'ウィジェット サービスを始める',
+        );
+
+        await page.selectLanguage('English');
+        await page.waitPageLoad();
+        expect(await browser.getUrl()).not.toContain('/ja-jp/');
+        expect(await browser.getUrl()).toContain('get-started.html');
+        expect(await (await page.getContentHeading()).getText()).toContain('Get Started');
+    });
+});
+
+describe('Docs content type > external link', () => {
+    it('exposes the real href and opens the external link in a new tab', async () => {
+        page = new DocsPage('/docs/docs-content-type-example/get-started.html');
+        page.open();
+        await page.waitPageLoad();
+        await page.waitForSidebar();
+
+        const anchor = await page.getTileAnchor('Salesforce Developers');
+        expect(await anchor.getAttribute('href')).toContain('https://developer.salesforce.com');
+        expect(await anchor.getAttribute('target')).toBe('_blank');
+    });
+});
+
+describe('Docs content type > Liquid templating', () => {
+    beforeEach(async () => {
+        page = new DocsPage('/docs/docs-content-type-example/liquid-widgets.html');
+        page.open();
+        await page.waitPageLoad();
+    });
+
+    it('resolves frontmatter assigns and liquid.data values in the body', async () => {
+        const content = await $('>>>doc-content-layout');
+        const text = await content.getText();
+        const html = await content.getHTML();
+
+        expect(text).toContain('Widget Automation');
+        expect(text).toContain('Hello from the docs liquid data file');
+        expect(html).not.toContain('{% assign');
+        expect(html).not.toContain('{{ feature }}');
+        expect(html).not.toContain('{{ data.tagline }}');
+    });
+
+    it('resolves repository-level variables from content-config.yml', async () => {
+        const content = await $('>>>doc-content-layout');
+        const text = await content.getText();
+        const html = await content.getHTML();
+
+        expect(text).toContain('Salesforce Platform');
+        expect(text).toContain('62.0');
+        expect(html).not.toContain('{{ variables.platform');
+    });
+
+    it('renders a loop over a liquid.data array', async () => {
+        const content = await $('>>>doc-content-layout');
+        const text = await content.getText();
+        const html = await content.getHTML();
+
+        expect(text).toContain('createWidget()');
+        expect(text).toContain('updateWidget()');
+        expect(text).toContain('deleteWidget()');
+        expect(html).not.toContain('for operation in data.operations');
+    });
+
+    it('resolves output expressions inside code blocks but keeps tags literal', async () => {
+        const codeBlockElement = await $('>>>.code-block-content');
+        const codeBlock = await codeBlockElement.shadow$('code');
+
+        expect(await codeBlock.isExisting()).toBeTruthy();
+
+        const codeText = await codeBlock.getText();
+        // {{ }} outputs resolve even inside code blocks.
+        expect(codeText).not.toContain('{{ data.tagline }}');
+        expect(codeText).toContain('Hello from the docs liquid data file');
+        expect(codeText).toContain('Widget Automation');
+        // {% %} tags stay literal inside code blocks.
+        expect(codeText).toContain('for op in ops');
+    });
+
+    it('renders a shared partial pulled in via include and its capture blocks', async () => {
+        const content = await $('>>>doc-content-layout');
+        const text = await content.getText();
+        const html = await content.getHTML();
+
+        expect(text).toContain('Reusable Tip');
+        expect(text).toContain('Widgets are created and managed through the Widgets API');
+        expect(text).toContain('Reusable Note');
+        expect(text).toContain('Every widget has a unique identifier');
+        // Dash-form tags are the fixture's real (resolved) tags; the bare "{% include %}"
+        // in the prose renders as literal inline code, so assert on the dash form only.
+        expect(html).not.toContain('{%- include');
+        expect(html).not.toContain('{%- capture');
+        expect(html).not.toContain('{{ liquid-widgets-reuse-tip }}');
+    });
+});
+
+describe('Docs content type > Liquid data object format', () => {
+    it('loads multiple data files each under a named key', async () => {
+        page = new DocsPage('/docs/docs-content-type-example/liquid-multi-data.html');
+        page.open();
+        await page.waitPageLoad();
+
+        const content = await $('>>>doc-content-layout');
+        const text = await content.getText();
+        const html = await content.getHTML();
+
+        expect(text).toContain('Hello from the docs liquid data file');
+        expect(text).toContain('Second data file loaded under a named key');
+        expect(html).not.toContain('{{ data.one.tagline }}');
+        expect(html).not.toContain('{{ two.summary }}');
+    });
+});
+
+describe('Docs content type > Liquid templating (ja-jp)', () => {
+    let jaLiquidEnabled = false;
+    const widgetsPath = '/docs/ja-jp/docs-content-type-example/liquid-widgets.html';
+
+    before(async () => {
+        try {
+            page = new DocsPage(widgetsPath);
+            page.open();
+            await page.waitPageLoad();
+
+            const content = await $('>>>doc-content-layout');
+            const text = await content.getText();
+            const html = await content.getHTML();
+
+            const hasLiquidOutput = text.includes(
+                'ドキュメント Liquid データ ファイルからこんにちは',
+            );
+            const hasRawSyntax = html.includes('{% assign') || html.includes('{{ data.tagline }}');
+
+            jaLiquidEnabled = hasLiquidOutput && !hasRawSyntax;
+        } catch (e) {
+            jaLiquidEnabled = false;
+        }
+    });
+
+    beforeEach(async () => {
+        if (jaLiquidEnabled) {
+            page = new DocsPage(widgetsPath);
+            page.open();
+            await page.waitPageLoad();
+        }
+    });
+
+    it('resolves frontmatter assigns and liquid.data values in a localized topic', async function () {
+        if (!jaLiquidEnabled) {
+            this.skip();
+        }
+
+        const content = await $('>>>doc-content-layout');
+        const text = await content.getText();
+        const html = await content.getHTML();
+
+        expect(text).toContain('ウィジェット オートメーション');
+        expect(text).toContain('ドキュメント Liquid データ ファイルからこんにちは');
+        expect(html).not.toContain('{% assign');
+        expect(html).not.toContain('{{ data.tagline }}');
+    });
+
+    it('resolves repository-level variables in a localized topic', async function () {
+        if (!jaLiquidEnabled) {
+            this.skip();
+        }
+
+        const content = await $('>>>doc-content-layout');
+        const text = await content.getText();
+        const html = await content.getHTML();
+
+        expect(text).toContain('Salesforce Platform');
+        expect(text).toContain('62.0');
+        expect(html).not.toContain('{{ variables.platform');
+    });
+
+    it('renders a loop and an included partial capture block in a localized topic', async function () {
+        if (!jaLiquidEnabled) {
+            this.skip();
+        }
+
+        const content = await $('>>>doc-content-layout');
+        const text = await content.getText();
+        const html = await content.getHTML();
+
+        expect(text).toContain('createWidget()');
+        expect(text).toContain('再利用可能なヒント');
+        expect(text).toContain('ウィジェットは Widgets API を通じて作成および管理されます');
+        expect(html).not.toContain('for operation in data.operations');
+        expect(html).not.toContain('{%- include');
+        expect(html).not.toContain('{%- capture');
+    });
+});
+
+describe('Docs content type > Liquid data object format (ja-jp)', () => {
+    let jaLiquidEnabled = false;
+    const multiDataPath = '/docs/ja-jp/docs-content-type-example/liquid-multi-data.html';
+
+    before(async () => {
+        try {
+            page = new DocsPage(multiDataPath);
+            page.open();
+            await page.waitPageLoad();
+
+            const content = await $('>>>doc-content-layout');
+            const text = await content.getText();
+            const html = await content.getHTML();
+
+            const hasLiquidOutput = text.includes(
+                'ドキュメント Liquid データ ファイルからこんにちは',
+            );
+            const hasRawSyntax =
+                html.includes('{{ data.one.tagline }}') || html.includes('{{ two.summary }}');
+
+            jaLiquidEnabled = hasLiquidOutput && !hasRawSyntax;
+        } catch (e) {
+            jaLiquidEnabled = false;
+        }
+    });
+
+    it('loads multiple data files each under a named key in a localized topic', async function () {
+        if (!jaLiquidEnabled) {
+            this.skip();
+        }
+
+        page = new DocsPage(multiDataPath);
+        page.open();
+        await page.waitPageLoad();
+
+        const content = await $('>>>doc-content-layout');
+        const text = await content.getText();
+        const html = await content.getHTML();
+
+        expect(text).toContain('ドキュメント Liquid データ ファイルからこんにちは');
+        expect(text).toContain('名前付きキーの下に読み込まれる 2 番目のデータ ファイル');
+        expect(html).not.toContain('{{ data.one.tagline }}');
+        expect(html).not.toContain('{{ two.summary }}');
+    });
+});
+
 describe('Docs content type > error routes', () => {
     const expectNotFoundPage = async (): Promise<void> => {
         const errorComponent = await $('dx-error');

package/src/shared/specs/liquid-advanced.test.ts

@@ -1,3 +1,4 @@
+import DocsPage from '../pageobjects/docs.page';
 import GuidePage from '../pageobjects/guide.page';
 
 let page: GuidePage;
@@ -54,3 +55,56 @@ describe('Liquid Template Rendering — Advanced', () => {
         expect(text.includes('previewFuture')).toBeTruthy();
     });
 });
+
+describe('Docs content type > future filter', () => {
+    let docsFutureEnabled = false;
+    const overviewPath = '/docs/docs-content-type-example/get-started.html';
+
+    before(async () => {
+        try {
+            const docsPage = new DocsPage(overviewPath);
+            docsPage.open();
+            await docsPage.waitPageLoad();
+
+            const content = await $('>>>doc-content-layout');
+            const text = await content.getText();
+
+            docsFutureEnabled = text.includes(
+                'hidden in production and excluded from localization unless',
+            );
+        } catch (e) {
+            docsFutureEnabled = false;
+        }
+    });
+
+    it('renders an inline future block when previewFuture is enabled', async function () {
+        if (!docsFutureEnabled) {
+            this.skip();
+        }
+
+        const docsPage = new DocsPage(overviewPath);
+        docsPage.open();
+        await docsPage.waitPageLoad();
+
+        const content = await $('>>>doc-content-layout');
+        const text = await content.getText();
+        const html = await content.getHTML();
+
+        expect(text).toContain('hidden in production and excluded from localization unless');
+        expect(html).not.toContain('{% future');
+    });
+
+    it('renders the future topic page when previewFuture is enabled', async function () {
+        if (!docsFutureEnabled) {
+            this.skip();
+        }
+
+        const docsPage = new DocsPage('/docs/docs-content-type-example/upcoming-graphql.html');
+        docsPage.open();
+        await docsPage.waitPageLoad();
+
+        expect(await (await docsPage.getContentHeading()).getText()).toContain(
+            'Upcoming: GraphQL API',
+        );
+    });
+});

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

@@ -222,3 +222,100 @@ describe('Liquid Template Rendering', () => {
         expect(text.includes('Liquid is a templating language supported in SFDocs')).toBeTruthy();
     });
 });
+
+describe('Liquid Template Rendering — Localized (ja-jp)', () => {
+    let jaLiquidEnabled = false;
+    const quickstartPath = '/docs/ja-jp/liquid-project/guide/liquid-quickstart.html';
+
+    before(async () => {
+        try {
+            page = new GuidePage(quickstartPath);
+            await browser.url(page.path);
+            await page.waitPageLoad();
+
+            const content = await $('>>>doc-content-layout');
+            const text = await content.getText();
+            const html = await content.getHTML();
+
+            const hasLiquidOutput = text.includes('data.yaml からこんにちは');
+            const hasRawSyntax =
+                html.includes('{% assign topic') || html.includes('{{ data.greeting }}');
+
+            jaLiquidEnabled = hasLiquidOutput && !hasRawSyntax;
+        } catch (e) {
+            jaLiquidEnabled = false;
+        }
+    });
+
+    beforeEach(async () => {
+        if (jaLiquidEnabled) {
+            page = new GuidePage(quickstartPath);
+            await browser.url(page.path);
+            await page.waitPageLoad();
+        }
+    });
+
+    it('Should render frontmatter assigns and data.yaml values in Japanese', async function () {
+        if (!jaLiquidEnabled) {
+            this.skip();
+        }
+
+        const content = await $('>>>doc-content-layout');
+        const text = await content.getText();
+
+        expect(text.includes('ライターのための GitHub')).toBeTruthy();
+        expect(text.includes('data.yaml からこんにちは')).toBeTruthy();
+    });
+
+    it('Should render repository-level variables in a localized topic', async function () {
+        if (!jaLiquidEnabled) {
+            this.skip();
+        }
+
+        const content = await $('>>>doc-content-layout');
+        const text = await content.getText();
+        const html = await content.getHTML();
+
+        expect(text.includes('Salesforce Platform')).toBeTruthy();
+        expect(text.includes('62.0')).toBeTruthy();
+        expect(html.includes('{{ variables.platform')).toBeFalsy();
+    });
+
+    it('Should render a loop and an included partial capture block in Japanese', async function () {
+        if (!jaLiquidEnabled) {
+            this.skip();
+        }
+
+        const content = await $('>>>doc-content-layout');
+        const text = await content.getText();
+        const html = await content.getHTML();
+
+        expect(text.includes('create()')).toBeTruthy();
+        expect(text.includes('再利用可能なヒント')).toBeTruthy();
+        expect(
+            text.includes('ウィジェットは Widgets API を通じて作成および管理されます'),
+        ).toBeTruthy();
+        // Dash-form tags are the fixture's real (resolved) tags; the bare "{% include %}"
+        // in the prose renders as literal inline code, so assert on the dash form only.
+        expect(html.includes('{%- include')).toBeFalsy();
+        expect(html.includes('{%- capture')).toBeFalsy();
+    });
+
+    it('Should render liquid.data object format in a localized topic', async function () {
+        if (!jaLiquidEnabled) {
+            this.skip();
+        }
+
+        const multiDataPage = new GuidePage('/docs/ja-jp/liquid-project/guide/multi-data.html');
+        await browser.url(multiDataPage.path);
+        await multiDataPage.waitPageLoad();
+
+        const content = await $('>>>doc-content-layout');
+        const text = await content.getText();
+        const html = await content.getHTML();
+
+        expect(text.includes('小売店舗や顧客サイト')).toBeTruthy();
+        expect(html.includes('{{ data.one.summary }}')).toBeFalsy();
+        expect(html.includes('{{ two.summary }}')).toBeFalsy();
+    });
+});

package/src/shared/specs/redoc-reference.test.ts

@@ -187,11 +187,9 @@ describe('Redoc API Reference page', () => {
 
             it('should show arrow button after OAS reference titles', async () => {
                 const sideBarContent = await refPage.getSidebarItems();
-
-                const secondItem = sideBarContent[1];
-                const treeItem = await secondItem.shadow$('dx-tree-item');
-                const treeTile = await treeItem.shadow$('a > dx-tree-tile');
-                const arrowIcon = await treeTile.shadow$(
+                const treeItem = await sideBarContent[1].shadow$('dx-tree-item');
+                const tile = await refPage.getTreeItemTile(treeItem);
+                const arrowIcon = await tile.shadow$(
                     'a > div[role="heading"] > div.tile-forward-arrow',
                 );
 

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