From 1e7c9a5f400554a22dd7cc09917e5eff35bd8ccb Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Mon, 24 Aug 2026 15:14:52 -0400 Subject: [PATCH 1/5] feat(home): offer VS Code alongside Docker in the quick start DocumentDB Local shipped in the VS Code extension's 0.10.0 release: the extension now creates and starts the container itself, so someone already working in VS Code no longer needs to run Docker by hand and then type a port, username, password and TLS choice back into a connection wizard. The home page only offered the Docker command, so that path was invisible to the people it was built for -- the ones who arrive at the site without the extension and leave with a terminal command. Docker stays selected by default. It works everywhere and needs nothing beyond Docker itself, while the VS Code path only pays off for people who already live in that editor, so it is offered rather than assumed. The install link comes before the deep link, and neither appears alone. A vscode:// URL for an extension that is not installed does nothing visible at all -- no error, no navigation -- so presenting it on its own would leave a first-time visitor clicking a button that silently does nothing. The heading moves from 'Run locally with Docker' to 'Run DocumentDB locally', since it now covers both. The run-with-docker anchor is kept: nothing in the repository links to it, but it is a public URL and it still lands on the right card. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Guanzhou Song --- app/components/QuickStartTabs.tsx | 159 ++++++++++++++++++++++++++++++ app/page.tsx | 56 ++++++----- app/services/externalLinks.ts | 14 +++ 3 files changed, 207 insertions(+), 22 deletions(-) create mode 100644 app/components/QuickStartTabs.tsx diff --git a/app/components/QuickStartTabs.tsx b/app/components/QuickStartTabs.tsx new file mode 100644 index 0000000..bf0a1df --- /dev/null +++ b/app/components/QuickStartTabs.tsx @@ -0,0 +1,159 @@ +"use client"; + +import Link from "next/link"; +import { useRef, useState } from "react"; +import CommandSnippet from "./CommandSnippet"; + +export type QuickStartStep = { + step: string; + description: string; +}; + +type QuickStartTabsProps = { + dockerCommand: string; + dockerSteps: QuickStartStep[]; + vscodeSteps: QuickStartStep[]; + /** Deep link that opens the extension's DocumentDB Local setup wizard. */ + vscodeDeepLinkUrl: string; + /** Marketplace page, for visitors who do not have the extension yet. */ + vscodeMarketplaceUrl: string; +}; + +const TABS = [ + { id: "docker", label: "Docker" }, + { id: "vscode", label: "VS Code" }, +] as const; + +type TabId = (typeof TABS)[number]["id"]; + +function StepList({ steps }: { steps: QuickStartStep[] }) { + return ( +
    + {steps.map((item) => ( +
  1. + + {item.step} + +

    {item.description}

    +
    2. + ))} +
+ ); +} + +/** + * The home page quick start, offering the two ways to get a local DocumentDB running. + * + * Docker stays first because it is the path that works everywhere and needs nothing installed + * beyond Docker itself. The VS Code path is newer and shorter — the extension provisions the + * container itself — but only pays off for people who already work in VS Code, so it is offered + * rather than assumed. + */ +export default function QuickStartTabs({ + dockerCommand, + dockerSteps, + vscodeSteps, + vscodeDeepLinkUrl, + vscodeMarketplaceUrl, +}: QuickStartTabsProps) { + const [activeTab, setActiveTab] = useState("docker"); + const tabRefs = useRef>({}); + + // Arrow keys move between tabs, which is what a tablist is expected to do; without it the + // only way through is Tab, and that leaves the panel. + const onTabKeyDown = (event: React.KeyboardEvent) => { + if (event.key !== "ArrowRight" && event.key !== "ArrowLeft") { + return; + } + + event.preventDefault(); + const currentIndex = TABS.findIndex((tab) => tab.id === activeTab); + const delta = event.key === "ArrowRight" ? 1 : -1; + const next = TABS[(currentIndex + delta + TABS.length) % TABS.length]; + + setActiveTab(next.id); + tabRefs.current[next.id]?.focus(); + }; + + return ( +
+
+ {TABS.map((tab) => { + const isActive = tab.id === activeTab; + + return ( + + ); + })} +
+ + + + +
+ ); +} diff --git a/app/page.tsx b/app/page.tsx index a8a7098..54306ea 100644 --- a/app/page.tsx +++ b/app/page.tsx @@ -1,7 +1,11 @@ import Image from "next/image"; import Link from "next/link"; -import CommandSnippet from "./components/CommandSnippet"; -import { documentdbKubernetesOperatorQuickStartUrl } from "./services/externalLinks"; +import QuickStartTabs from "./components/QuickStartTabs"; +import { + documentdbKubernetesOperatorQuickStartUrl, + documentdbVsCodeExtensionMarketplaceUrl, + documentdbVsCodeLocalQuickStartDeepLink, +} from "./services/externalLinks"; import { getMetadata } from "./services/metadataService"; import { documentdbGitHubForks, @@ -39,7 +43,7 @@ const quickRunCommand = `docker run -dt --name documentdb \\ --username \\ --password `; -const quickStartSteps = [ +const dockerQuickStartSteps = [ { step: "01", description: "Run DocumentDB Local with Docker.", @@ -54,6 +58,23 @@ const quickStartSteps = [ }, ]; +const vscodeQuickStartSteps = [ + { + step: "01", + description: "Install the DocumentDB extension for Visual Studio Code.", + }, + { + step: "02", + description: + "Open the DocumentDB Local setup and let the extension create and start the container for you.", + }, + { + step: "03", + description: + "Browse databases, run queries, and edit documents without leaving the editor.", + }, +]; + const kubernetesOperatorEntryPoints = [ { title: "Local clusters", @@ -372,29 +393,20 @@ export default function Home() { Quick start

- Run locally with Docker + Run DocumentDB locally

- Start DocumentDB Local with Docker, then connect on port - 10260. + Start DocumentDB Local with Docker, or let the VS Code + extension set it up for you.

- -
    - {quickStartSteps.map((item) => ( -
  1. - - {item.step} - -

    - {item.description} -

    -
    2. - ))} -
+
Date: Thu, 10 Sep 2026 10:16:21 -0400 Subject: [PATCH 2/5] Refresh VS Code quick start for released local setup Require extension 0.10.1 or later, explain the Docker prerequisite and wizard actions, and provide the Command Palette fallback. The /local deep link shipped in microsoft/vscode-documentdb#898 and no longer needs a release blocker. Preserve the Docker default and add rendered-homepage regression coverage. Signed-off-by: Guanzhou Song Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- app/components/QuickStartTabs.tsx | 24 +++++------ app/page.tsx | 7 ++-- app/services/externalLinks.ts | 8 ---- tests/quickStart.test.ts | 69 +++++++++++++++++++++++++++++++ 4 files changed, 84 insertions(+), 24 deletions(-) create mode 100644 tests/quickStart.test.ts diff --git a/app/components/QuickStartTabs.tsx b/app/components/QuickStartTabs.tsx index bf0a1df..a01b37a 100644 --- a/app/components/QuickStartTabs.tsx +++ b/app/components/QuickStartTabs.tsx @@ -44,14 +44,6 @@ function StepList({ steps }: { steps: QuickStartStep[] }) { ); } -/** - * The home page quick start, offering the two ways to get a local DocumentDB running. - * - * Docker stays first because it is the path that works everywhere and needs nothing installed - * beyond Docker itself. The VS Code path is newer and shorter — the extension provisions the - * container itself — but only pays off for people who already work in VS Code, so it is offered - * rather than assumed. - */ export default function QuickStartTabs({ dockerCommand, dockerSteps, @@ -131,6 +123,10 @@ export default function QuickStartTabs({ aria-labelledby="quickstart-tab-vscode" hidden={activeTab !== "vscode"} > +

+ Requires Docker Engine or Docker Desktop running Linux containers in + your VS Code environment. +

Get the extension - {/* - * A `vscode://` link does nothing at all when VS Code is not installed — no error, no - * navigation — so it is offered second and never on its own. Someone arriving without - * the extension gets the install link first and this becomes the obvious next step. - */}
+

+ If the link does not open setup, run{" "} + + DocumentDB: Set up DocumentDB Local + {" "} + from the VS Code Command Palette. +

); diff --git a/app/page.tsx b/app/page.tsx index 54306ea..389567e 100644 --- a/app/page.tsx +++ b/app/page.tsx @@ -61,17 +61,18 @@ const dockerQuickStartSteps = [ const vscodeQuickStartSteps = [ { step: "01", - description: "Install the DocumentDB extension for Visual Studio Code.", + description: + "Install or update DocumentDB for VS Code to version 0.10.1 or later.", }, { step: "02", description: - "Open the DocumentDB Local setup and let the extension create and start the container for you.", + "Open setup, confirm if prompted, select Continue, then review the defaults and select Start DocumentDB Local.", }, { step: "03", description: - "Browse databases, run queries, and edit documents without leaving the editor.", + "When setup finishes, select Open Connection to browse data and run queries.", }, ]; diff --git a/app/services/externalLinks.ts b/app/services/externalLinks.ts index 645203b..7a3ada9 100644 --- a/app/services/externalLinks.ts +++ b/app/services/externalLinks.ts @@ -17,13 +17,5 @@ export const documentdbKubernetesOperatorGitHubUrl = export const documentdbVsCodeExtensionMarketplaceUrl = 'https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-documentdb'; -// Deep link into the extension's DocumentDB Local setup wizard. -// -// The path names the action; an empty path means "connect", which is what every link published -// before the extension supported actions relies on. See the extension's -// docs/user-manual/how-to-construct-url.md for the full vocabulary. -// -// Requires the extension to be installed: a `vscode://` URL for an absent extension does nothing -// visible at all, so never present this without the marketplace link beside it. export const documentdbVsCodeLocalQuickStartDeepLink = 'vscode://ms-azuretools.vscode-documentdb/local'; diff --git a/tests/quickStart.test.ts b/tests/quickStart.test.ts new file mode 100644 index 0000000..525f278 --- /dev/null +++ b/tests/quickStart.test.ts @@ -0,0 +1,69 @@ +import { createElement } from 'react'; +import { renderToStaticMarkup } from 'react-dom/server'; +import { describe, expect, it } from 'vitest'; +import Home from '../app/page'; +import { + documentdbVsCodeExtensionMarketplaceUrl, + documentdbVsCodeLocalQuickStartDeepLink, +} from '../app/services/externalLinks'; + +const html = renderToStaticMarkup(createElement(Home)); + +describe('homepage local quick start', () => { + it('preserves the public anchor and Docker as the default tab', () => { + expect(html).toContain('id="run-with-docker"'); + expect(html).toMatch( + /id="quickstart-tab-docker" aria-selected="true" aria-controls="quickstart-panel-docker" tabindex="0"/, + ); + expect(html).toMatch( + /id="quickstart-tab-vscode" aria-selected="false" aria-controls="quickstart-panel-vscode" tabindex="-1"/, + ); + expect(html).toMatch( + /id="quickstart-panel-docker" aria-labelledby="quickstart-tab-docker">/, + ); + expect(html).toMatch( + /id="quickstart-panel-vscode" aria-labelledby="quickstart-tab-vscode" hidden=""/, + ); + expect(html).toContain('docker run -dt --name documentdb'); + expect(html).toContain('-p 10260:10260'); + expect(html).toContain( + 'ghcr.io/documentdb/documentdb/documentdb-local:latest', + ); + }); + + it('offers the marketplace before the supported local setup deep link', () => { + expect(documentdbVsCodeExtensionMarketplaceUrl).toBe( + 'https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-documentdb', + ); + expect(documentdbVsCodeLocalQuickStartDeepLink).toBe( + 'vscode://ms-azuretools.vscode-documentdb/local', + ); + const marketplace = html.indexOf( + `href="${documentdbVsCodeExtensionMarketplaceUrl}"`, + ); + const setup = html.indexOf( + `href="${documentdbVsCodeLocalQuickStartDeepLink}"`, + ); + expect(marketplace).toBeGreaterThan(-1); + expect(setup).toBeGreaterThan(marketplace); + }); + + it('states the shipped minimum version and Docker prerequisite', () => { + expect(html).toContain('version 0.10.1 or later'); + expect(html).toContain( + 'Requires Docker Engine or Docker Desktop running Linux containers in your VS Code environment.', + ); + }); + + it('describes the setup actions and provides a Command Palette fallback', () => { + expect(html).toContain( + 'Open setup, confirm if prompted, select Continue, then review the defaults and select Start DocumentDB Local.', + ); + expect(html).toContain( + 'When setup finishes, select Open Connection to browse data and run queries.', + ); + expect(html).toContain('If the link does not open setup, run '); + expect(html).toContain('DocumentDB: Set up DocumentDB Local'); + expect(html).toContain('from the VS Code Command Palette.'); + }); +}); From 95c246aaedc9650bba5f001cbd5cfb0d6932cb57 Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Thu, 10 Sep 2026 10:19:32 -0400 Subject: [PATCH 3/5] Enable JSX rendering in homepage regression tests Use Vite's automatic JSX runtime for Vitest without changing Next.js's preserve setting or adding dependencies. Signed-off-by: Guanzhou Song Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: b2b0079f-68de-4316-8592-64ccfa495ee3 --- vitest.config.ts | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 vitest.config.ts diff --git a/vitest.config.ts b/vitest.config.ts new file mode 100644 index 0000000..21215b0 --- /dev/null +++ b/vitest.config.ts @@ -0,0 +1,9 @@ +import { defineConfig } from 'vitest/config'; + +export default defineConfig({ + oxc: { + jsx: { + runtime: 'automatic', + }, + }, +}); From cb4c620998f457aaef76fd610cf225869d333669 Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Thu, 10 Sep 2026 10:29:48 -0400 Subject: [PATCH 4/5] Name the link confirmation button in the VS Code quick start The setup step said "confirm if prompted" without naming what to confirm. The extension's deep-link handler shows a modal whose confirm button is labeled "Open setup", so name it, matching how the remaining steps already name Continue, Start DocumentDB Local, and Open Connection. Verified against microsoft/vscode-documentdb main (013e429f): src/vscodeUriHandler.ts shows the confirmation, and LocalQuickStart.tsx drives introduction -> Continue -> configure -> Start DocumentDB Local -> Open Connection. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_017dU6YABKoUxKLU2AB1qeH1 --- app/page.tsx | 2 +- tests/quickStart.test.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/app/page.tsx b/app/page.tsx index 389567e..b29a5c7 100644 --- a/app/page.tsx +++ b/app/page.tsx @@ -67,7 +67,7 @@ const vscodeQuickStartSteps = [ { step: "02", description: - "Open setup, confirm if prompted, select Continue, then review the defaults and select Start DocumentDB Local.", + "Select Open setup when VS Code confirms the link, then Continue, review the defaults, and select Start DocumentDB Local.", }, { step: "03", diff --git a/tests/quickStart.test.ts b/tests/quickStart.test.ts index 525f278..1a468fe 100644 --- a/tests/quickStart.test.ts +++ b/tests/quickStart.test.ts @@ -57,7 +57,7 @@ describe('homepage local quick start', () => { it('describes the setup actions and provides a Command Palette fallback', () => { expect(html).toContain( - 'Open setup, confirm if prompted, select Continue, then review the defaults and select Start DocumentDB Local.', + 'Select Open setup when VS Code confirms the link, then Continue, review the defaults, and select Start DocumentDB Local.', ); expect(html).toContain( 'When setup finishes, select Open Connection to browse data and run queries.', From 0d5658024c18692806fee6fd742b1d992f046a17 Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Thu, 10 Sep 2026 10:47:34 -0400 Subject: [PATCH 5/5] Make the quick start readable to someone who has not seen the wizard A design and product review of the tabbed quick start found the VS Code panel narrated a wizard the reader has never seen, and led with a deep link that silently does nothing for the very person the tab is for. Copy: - The prerequisite now says the VS Code path still uses Docker, and that the extension never installs Docker or changes the user's system, rather than the jargon "in your VS Code environment". - Step 01 names what gets installed instead of pinning extension version 0.10.1, which is maintenance debt on a homepage and is noise for a new installer who gets the latest anyway. - Step 02 was a four-action transcript of wizard buttons; it now says click, allow, and follow the wizard. - Step 03 states the outcome, port and generated credentials, so the reader knows what they got. - The fallback names the likely cause instead of treating "no VS Code", "no extension", and "old extension" as the same thing. - The Docker steps drop the one that restated the command above it, add a first-run time expectation, and end on a concrete connect-and-query instead of "the setup you need". Structure: - Tabs are Terminal and VS Code. Labelling one "Docker" implied the other avoided Docker, when both start the same container. - Install the extension is now the primary action; the deep link is secondary, matching the order of the steps. - The card footer link follows the active tab and points at that path's full guide. Download packages is gone, since the hero already has Download pointing at the same page. - Each panel links to the other path so neither is hidden behind a tab. Presentation: - The tablist gets a solid active state and larger hit targets, so it reads as a control rather than as another badge between the Quick start chip and the numbered step markers. - The hero grid is items-start. It was items-center, and since the card is the taller column, switching tabs moved the DocumentDB headline. - Home and End keys move between tabs, per the ARIA authoring practices. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_017dU6YABKoUxKLU2AB1qeH1 --- app/components/QuickStartTabs.tsx | 105 ++++++++++++++++++++++-------- app/page.tsx | 37 ++++------- tests/quickStart.test.ts | 53 +++++++++++---- 3 files changed, 132 insertions(+), 63 deletions(-) diff --git a/app/components/QuickStartTabs.tsx b/app/components/QuickStartTabs.tsx index a01b37a..26af5cb 100644 --- a/app/components/QuickStartTabs.tsx +++ b/app/components/QuickStartTabs.tsx @@ -17,10 +17,15 @@ type QuickStartTabsProps = { vscodeDeepLinkUrl: string; /** Marketplace page, for visitors who do not have the extension yet. */ vscodeMarketplaceUrl: string; + /** Full guide for each path, linked from the footer of the matching panel. */ + dockerDocsUrl: string; + vscodeDocsUrl: string; }; +// "Terminal" rather than "Docker": both paths run the same Docker container, and labelling one +// of them "Docker" implies the other avoids it. const TABS = [ - { id: "docker", label: "Docker" }, + { id: "terminal", label: "Terminal" }, { id: "vscode", label: "VS Code" }, ] as const; @@ -32,9 +37,9 @@ function StepList({ steps }: { steps: QuickStartStep[] }) { {steps.map((item) => (
  • - + {item.step}

    {item.description}

    @@ -50,24 +55,42 @@ export default function QuickStartTabs({ vscodeSteps, vscodeDeepLinkUrl, vscodeMarketplaceUrl, + dockerDocsUrl, + vscodeDocsUrl, }: QuickStartTabsProps) { - const [activeTab, setActiveTab] = useState("docker"); + const [activeTab, setActiveTab] = useState("terminal"); const tabRefs = useRef>({}); + const selectTab = (id: TabId) => { + setActiveTab(id); + tabRefs.current[id]?.focus(); + }; + // Arrow keys move between tabs, which is what a tablist is expected to do; without it the - // only way through is Tab, and that leaves the panel. + // only way through is Tab, and that leaves the panel. Home/End jump to the ends, per the + // ARIA authoring practices for tabs. const onTabKeyDown = (event: React.KeyboardEvent) => { - if (event.key !== "ArrowRight" && event.key !== "ArrowLeft") { - return; - } - - event.preventDefault(); const currentIndex = TABS.findIndex((tab) => tab.id === activeTab); - const delta = event.key === "ArrowRight" ? 1 : -1; - const next = TABS[(currentIndex + delta + TABS.length) % TABS.length]; - setActiveTab(next.id); - tabRefs.current[next.id]?.focus(); + switch (event.key) { + case "ArrowRight": + case "ArrowLeft": { + event.preventDefault(); + const delta = event.key === "ArrowRight" ? 1 : -1; + selectTab(TABS[(currentIndex + delta + TABS.length) % TABS.length].id); + break; + } + case "Home": + event.preventDefault(); + selectTab(TABS[0].id); + break; + case "End": + event.preventDefault(); + selectTab(TABS[TABS.length - 1].id); + break; + default: + break; + } }; return ( @@ -75,7 +98,7 @@ export default function QuickStartTabs({
    {TABS.map((tab) => { const isActive = tab.id === activeTab; @@ -95,9 +118,11 @@ export default function QuickStartTabs({ tabIndex={isActive ? 0 : -1} onClick={() => setActiveTab(tab.id)} onKeyDown={onTabKeyDown} - className={`rounded-full px-4 py-1.5 text-xs font-semibold transition-colors ${ + // Solid active state so the tablist reads as a control rather than as another + // badge next to the "Quick start" chip and the numbered step markers. + className={`flex-1 rounded-full px-5 py-3 text-sm font-semibold transition-colors sm:flex-none ${ isActive - ? "bg-blue-500/20 text-blue-100" + ? "bg-blue-500 text-white" : "text-gray-400 hover:text-gray-200" }`} > @@ -109,12 +134,23 @@ export default function QuickStartTabs({ + +
    + + {activeTab === "vscode" + ? "Full VS Code guide" + : "Full Docker guide"} + +
    ); } diff --git a/app/page.tsx b/app/page.tsx index b29a5c7..2d301d8 100644 --- a/app/page.tsx +++ b/app/page.tsx @@ -46,15 +46,18 @@ const quickRunCommand = `docker run -dt --name documentdb \\ const dockerQuickStartSteps = [ { step: "01", - description: "Run DocumentDB Local with Docker.", + description: + "Run the command above. Docker pulls the image on the first run, so give it about a minute.", }, { step: "02", - description: "Connect on port 10260 with your app, shell, or client.", + description: + "Connect on port 10260 with mongosh, any MongoDB driver, or your app.", }, { step: "03", - description: "Continue with the docs or Linux packages for the setup you need.", + description: + "Run your first query. The Docker guide has connection strings and sample data.", }, ]; @@ -62,17 +65,17 @@ const vscodeQuickStartSteps = [ { step: "01", description: - "Install or update DocumentDB for VS Code to version 0.10.1 or later.", + "Install the free DocumentDB for VS Code extension from the Marketplace.", }, { step: "02", description: - "Select Open setup when VS Code confirms the link, then Continue, review the defaults, and select Start DocumentDB Local.", + "Select Open setup in VS Code and allow it to open the link. The wizard starts DocumentDB Local with defaults you can review.", }, { step: "03", description: - "When setup finishes, select Open Connection to browse data and run queries.", + "You get a container on port 10260 with generated credentials. Select Open Connection to browse data and run your first query.", }, ]; @@ -338,7 +341,7 @@ export default function Home() {
    -
    +

    Open source document database @@ -397,8 +400,8 @@ export default function Home() { Run DocumentDB locally

    - Start DocumentDB Local with Docker, or let the VS Code - extension set it up for you. + Run it from your terminal, or let the VS Code extension set it + up for you. Both start the same DocumentDB Local container.

    -
    - - Docker quick start - - - Download packages - -
    diff --git a/tests/quickStart.test.ts b/tests/quickStart.test.ts index 1a468fe..b7d9b09 100644 --- a/tests/quickStart.test.ts +++ b/tests/quickStart.test.ts @@ -10,16 +10,16 @@ import { const html = renderToStaticMarkup(createElement(Home)); describe('homepage local quick start', () => { - it('preserves the public anchor and Docker as the default tab', () => { + it('preserves the public anchor and the terminal path as the default tab', () => { expect(html).toContain('id="run-with-docker"'); expect(html).toMatch( - /id="quickstart-tab-docker" aria-selected="true" aria-controls="quickstart-panel-docker" tabindex="0"/, + /id="quickstart-tab-terminal" aria-selected="true" aria-controls="quickstart-panel-terminal" tabindex="0"/, ); expect(html).toMatch( /id="quickstart-tab-vscode" aria-selected="false" aria-controls="quickstart-panel-vscode" tabindex="-1"/, ); expect(html).toMatch( - /id="quickstart-panel-docker" aria-labelledby="quickstart-tab-docker">/, + /id="quickstart-panel-terminal" aria-labelledby="quickstart-tab-terminal">/, ); expect(html).toMatch( /id="quickstart-panel-vscode" aria-labelledby="quickstart-tab-vscode" hidden=""/, @@ -31,7 +31,15 @@ describe('homepage local quick start', () => { ); }); - it('offers the marketplace before the supported local setup deep link', () => { + it('labels the tabs by interface rather than implying one path avoids Docker', () => { + expect(html).toContain('>Terminal'); + expect(html).toContain('>VS Code'); + expect(html).toContain( + 'Both start the same DocumentDB Local container.', + ); + }); + + it('leads with installing the extension, then opening setup', () => { expect(documentdbVsCodeExtensionMarketplaceUrl).toBe( 'https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-documentdb', ); @@ -46,24 +54,45 @@ describe('homepage local quick start', () => { ); expect(marketplace).toBeGreaterThan(-1); expect(setup).toBeGreaterThan(marketplace); + expect(html).toContain('Install the extension'); + expect(html).toContain('Open setup in VS Code'); + }); + + it('states that the VS Code path still needs Docker and changes nothing else', () => { + expect(html).toContain( + 'Needs Docker Desktop or Docker Engine on the same machine as VS Code.', + ); + expect(html).toContain('It never installs Docker or changes your system.'); }); - it('states the shipped minimum version and Docker prerequisite', () => { - expect(html).toContain('version 0.10.1 or later'); + it('describes the setup outcome without pinning an extension version', () => { + expect(html).toContain( + 'Install the free DocumentDB for VS Code extension from the Marketplace.', + ); expect(html).toContain( - 'Requires Docker Engine or Docker Desktop running Linux containers in your VS Code environment.', + 'The wizard starts DocumentDB Local with defaults you can review.', ); + expect(html).toContain( + 'You get a container on port 10260 with generated credentials.', + ); + // A pinned minimum version on the homepage rots; the guide carries it instead. + expect(html).not.toContain('0.10.1'); }); - it('describes the setup actions and provides a Command Palette fallback', () => { + it('gives each path a concrete first query and a full guide', () => { expect(html).toContain( - 'Select Open setup when VS Code confirms the link, then Continue, review the defaults, and select Start DocumentDB Local.', + 'Connect on port 10260 with mongosh, any MongoDB driver, or your app.', ); + expect(html).toContain('Run your first query.'); + expect(html).toContain('href="/docs/getting-started/docker"'); + expect(html).toContain('Full Docker guide'); + }); + + it('provides a Command Palette fallback that names the likely cause', () => { expect(html).toContain( - 'When setup finishes, select Open Connection to browse data and run queries.', + 'If nothing happens, check that the extension is installed and up to', ); - expect(html).toContain('If the link does not open setup, run '); expect(html).toContain('DocumentDB: Set up DocumentDB Local'); - expect(html).toContain('from the VS Code Command Palette.'); + expect(html).toContain('from the Command Palette.'); }); });