Fix frontend e2e sidebar and WCAG regression failures by IEvangelist · Pull Request #672 · microsoft/aspire.dev

IEvangelist · 2026-04-04T03:28:12Z

Summary

Fixes #676

Also, adds tests!

This PR fixes the frontend end-to-end failures that were showing up in the sidebar regression test and the WCAG AA audit suite, and it also folds in the broader frontend hardening work that landed alongside those fixes.

What changed

stabilized the Playwright UI regression and WCAG suites, including the API sidebar collapse-state persistence flow on reload
hardened the shared accessibility helper so generated Starlight and Expressive Code blocks get stable labels, and made horizontally scrollable tables keyboard-focusable with generated labels where needed
converted the remaining authored frontend JavaScript maintenance scripts and related authored surfaces to TypeScript, including the RSS route and shared utilities
added broader frontend regression coverage: unit and end-to-end tests for analytics script delivery, cookie consent and preferences, RSS behavior, pivot behavior, and other UI regressions
added custom Astro component coverage with both runtime render tests and compile-time prop-contract tests so component props remain discoverable and typed for consumers
refactored heavier Astro frontmatter logic into shared TypeScript helpers, including the SimpleAppHostCode and floating icon layout logic, and normalized component prop typing across custom components
cleaned up the Playwright package and script setup by removing the redundant CLI package and duplicate browser install path while preserving a dedicated local install helper
updated the install CLI and VS Code extension docs so repeated code examples have distinct titles

Why

This work addressed a few related frontend maintenance issues at the same time:

the sidebar persistence test could race the post-reload UI state and intermittently interact with the wrong control before the page was ready
Axe was flagging duplicate landmark names on generated code block regions, especially on tablet and mobile layouts where OS-aware tabs can promote different code blocks into landmarks after hydration
mobile audit runs were also hitting scrollable table keyboard-access issues
several authored frontend scripts and utilities still relied on JavaScript, which limited type safety and made larger refactors riskier than necessary
the custom component surface needed stronger regression coverage so prop contracts and render behavior would stay stable as the frontend evolved

Validation

Ran targeted validation against the Astro dev server and frontend test suites:

pnpm --dir "e:\GitHub\aspire.dev\src\frontend" run test:unit:components
pnpm --dir "e:\GitHub\aspire.dev\src\frontend" exec playwright test tests/e2e/wcag-aa.spec.ts --project=desktop-chromium --project=tablet-chromium --project=mobile-chromium
pnpm --dir "e:\GitHub\aspire.dev\src\frontend" exec playwright test tests/e2e/rss.spec.ts
pnpm --dir "e:\GitHub\aspire.dev\src\frontend" exec playwright test tests/e2e/ui-regressions.spec.ts --project=desktop-chromium --grep "API sidebar collapse state persists across reloads" --repeat-each=3

Notes:

the 2 skipped tests from the earlier validation run were the tablet and mobile variants of API sidebar collapse state persists across reloads
that scenario intentionally skips on narrow viewports because the collapse and expand affordance only exists on wide desktop layouts

Copilot

Pull request overview

This PR addresses frontend Playwright E2E regressions and WCAG AA audit failures by stabilizing accessibility labeling (code blocks/tables), hardening sidebar-related tests, and moving analytics scripts to static public assets with new contract tests.

Changes:

Added/updated Playwright E2E suites (UI regressions, pivots, WCAG AA) plus Playwright config and CI workflow integration.
Improved a11y behavior by generating stable accessible labels for code regions and making horizontally scrollable tables keyboard-focusable.
Migrated analytics script delivery from Astro routes to static public/scripts/analytics/* and added unit/E2E contract tests.

Reviewed changes

Copilot reviewed 28 out of 30 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/frontend/tests/unit/analytics-script-contracts.test.js	Adds unit contract tests to ensure analytics scripts are referenced and present as static assets.
src/frontend/tests/e2e/wcag-aa.spec.js	Introduces Axe-based WCAG A/AA audits across key pages (marks large API page as slow).
src/frontend/tests/e2e/ui-regressions.spec.js	Adds regression coverage for install modal, cookie consent, footer prefs, synced tabs, and sidebar persistence.
src/frontend/tests/e2e/pivot-selector.spec.js	Adds E2E coverage for pivot selector query-string state/restore.
src/frontend/tests/e2e/helpers.js	Centralizes cookie dismissal and cookie-consent polling helpers for E2E tests.
src/frontend/tests/e2e/analytics-scripts.spec.js	Adds E2E smoke checks for analytics script endpoints and home-page references.
src/frontend/src/pages/track.js	Removes dynamic analytics route in favor of static public asset delivery.
src/frontend/src/pages/1ds.js	Removes dynamic analytics route in favor of static public asset delivery.
src/frontend/src/content/docs/get-started/install-cli.mdx	Updates repeated code samples with distinct titles to avoid a11y label collisions.
src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx	Updates repeated code sample titles to avoid duplicate accessible names.
src/frontend/src/components/MicrosoftFooter.astro	Adjusts footer column semantics/labeling to avoid landmark/name duplication.
src/frontend/src/components/FreeAndOpenSourceAside.astro	Tweaks heading semantics (h5→p) to align with accessibility changes.
src/frontend/src/components/FooterResources.astro	Adjusts footer column semantics/labeling to avoid landmark/name duplication.
src/frontend/src/components/FooterPreferences.astro	Adjusts footer semantics/markup consistency while preserving preferences behavior.
src/frontend/src/components/FooterLinks.astro	Refactors footer community links rendering and formatting.
src/frontend/src/components/FooterLegal.astro	Adjusts footer column semantics/labeling to avoid landmark/name duplication.
src/frontend/src/components/AppHostBuilder.astro	Formatting + minor style token adjustment affecting active toggle color.
src/frontend/src/components/api-reference/MemberCardBase.astro	Refactors markup (including section labels) and formatting for API member cards.
src/frontend/src/components/api-reference/MemberCard.astro	Refactors markup (including section labels) and formatting for API member cards.
src/frontend/src/components/AccessibleCodeButtons.astro	Adds code-region labeling + scrollable table focusability enhancements and reruns on navigation/resize.
src/frontend/public/scripts/analytics/track.js	Adds static analytics tracking bootstrap script under public assets.
src/frontend/public/scripts/analytics/1ds.js	Adds static 1DS bootstrap script under public assets.
src/frontend/pnpm-lock.yaml	Adds lock entries for Playwright Test + Axe Playwright dependencies.
src/frontend/playwright.config.mjs	Adds Playwright test runner configuration with multi-viewport projects and webServer.
src/frontend/package.json	Adds test scripts and Playwright/Axe devDependencies for E2E + a11y testing.
src/frontend/config/head.attrs.ts	Updates head script references to point to static analytics assets.
src/frontend/config/cookie.config.ts	Adjusts cookie-consent behavior for E2E via env flag.
package.json	Adds root-level `test` script that delegates to the frontend.
.gitignore	Ignores Playwright reports and test-results artifacts.
.github/workflows/frontend-build.yml	Adds unit + Playwright smoke tests, uploads reports, and summarizes quality gates in CI.

Files not reviewed (1)

src/frontend/pnpm-lock.yaml: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/frontend/src/components/FooterLinks.astro

src/frontend/src/components/AccessibleCodeButtons.astro

src/frontend/package.json

.github/workflows/frontend-build.yml

src/frontend/tests/e2e/wcag-aa.spec.ts

- Refactor MemberCardBase.astro for improved readability and structure. - Introduce Playwright configuration for end-to-end testing. - Add tests for analytics scripts to ensure correct loading and content. - Implement helper functions for cookie consent management in tests. - Create tests for pivot selector functionality and UI regressions. - Conduct WCAG AA compliance audits on key pages. - Establish unit tests for analytics script contracts to verify file existence and content.

…om components - Implemented helper functions for cookie consent management in e2e tests. - Created e2e tests for pivot selection and cookie consent behavior. - Added UI regression tests to verify analytics consent and theme persistence. - Conducted WCAG AA audits on key pages to ensure accessibility compliance. - Developed unit tests for analytics script contracts and custom Astro components. - Configured Vitest for unit testing with specific settings for Astro components.

- Implemented `update-samples.ts` to fetch and process sample data from GitHub, including downloading images and rewriting documentation links. - Created `update-ts-api.ts` to regenerate TypeScript API reference data using the AtsJsonGenerator tool, with checks for prerequisites like dotnet SDK and Aspire CLI. - Added end-to-end tests for RSS feed endpoint and link behavior in `rss.spec.ts`. - Introduced type-checking tests for component props in `component-props.contracts.ts`, ensuring proper prop validation across various components.

- Moved marker and collapse value shifting logic to a new shared file: SimpleAppHostCode.shared.ts. - Simplified SimpleAppHostCode.astro by utilizing the new shared functions. - Added a function to retrieve code snippets based on the selected language. - Introduced floating-icon-layout.ts for managing floating icon positions and animations in TopicHero component. - Updated TopicHero.astro to use the new floating icon layout logic. - Adjusted import paths across various components and tests for consistency. - Enhanced type definitions and improved code organization for better maintainability.

…ance

…collapse state persistence

…ing expectations

src/frontend/scripts/update-github-stats.ts

…it test for rendering - fixes #676

…t types

…l script

…eference

JamesNK

Nice work stabilizing the test suites and converting the scripts to TypeScript. Left a few comments — the 404 detection regression in FooterLinks and the OsAwareTabs instanceof check are the ones worth addressing; the rest are nits.

JamesNK · 2026-04-06T03:11:38Z

src/frontend/src/components/FooterLinks.astro

-const gitHubLink = links.filter(l => l.label == 'GitHub')[0].href || null;
-const discordLink = links.filter(l => l.label == 'Discord')[0].href || null;
-const is404 = Astro.locals.starlightRoute?.entry?.slug === "404";
+const gitHubLink = links.find((link) => link.label === 'GitHub')?.href ?? null;


This breaks 404 detection for localized pages. The old check Astro.locals.starlightRoute?.entry?.slug === "404" matched all locales (e.g. /ja/404/, /zh-CN/404/), but this pathname check only matches the English variants. Community links will incorrectly render on localized 404 pages.

Consider restoring the slug-based check, or using a regex/includes match on the pathname.

JamesNK · 2026-04-06T03:11:49Z

src/frontend/src/components/OsAwareTabs.astro

+            tab.setAttribute('aria-selected', isSelected ? 'true' : 'false');
+            tab.setAttribute('tabindex', isSelected ? '0' : '-1');
+          });
+


The findIndex check uses instanceof HTMLAnchorElement, but if Starlight renders tabs as <button> elements this will silently return -1 and activateTabByLabel will exit without switching any tab. The script then sets the localStorage preference at the bottom but the UI won't visually reflect it on first load.

Consider relaxing the check to tab instanceof HTMLElement (or just check tab.textContent) to handle both <a> and <button> tab implementations.

JamesNK · 2026-04-06T03:11:57Z

src/frontend/eslint.config.mjs

  },
+  {
+    files: ['tests/**/*.ts'],
+    ...tseslint.configs.disableTypeChecked,


This disables type-checked lint rules for all test files including tests/typecheck/component-props.contracts.ts, whose entire purpose is compile-time type validation via @ts-expect-error annotations. Consider narrowing the glob to just tests/e2e/**/*.ts if only the Playwright files are causing issues.

JamesNK · 2026-04-06T03:12:07Z

src/frontend/src/components/api-reference/MemberCard.astro

+      <aside class="api-experimental-aside">
+        <svg
+          width="16"
+          height="16"


Nit: the section labels (Parameters, Returns, Exceptions, Remarks, Examples) were demoted from <h5> to <p>. These are no longer in the heading hierarchy, which makes it harder for screen-reader users to navigate within a member card by headings. Since this file is one of the most heading-dense surfaces on the API reference, the <h5> elements were useful navigation landmarks.

Was this intentional (e.g. to fix an axe violation about heading order), or incidental?

Intentional, they should not have been headings before.

JamesNK · 2026-04-06T03:12:14Z

src/frontend/scripts/fetch-with-proxy.ts

+
+  const parsedUrl = url instanceof URL ? url : new URL(url);
+  return fetch(url, { ...options, agent: selectAgent(parsedUrl) });
+}


Nit: missing trailing newline at end of file.

* Fix PR 672 follow-up regressions * fix: add missing newline at end of fetch-with-proxy.ts * Refine frontend test lint overrides * Add FooterLinks 404 fallback coverage

Copilot AI review requested due to automatic review settings April 4, 2026 03:28

Copilot started reviewing on behalf of IEvangelist April 4, 2026 03:29 View session

Copilot AI reviewed Apr 4, 2026

View reviewed changes

IEvangelist added 7 commits April 4, 2026 11:35

Fix e2e accessibility and sidebar regressions

432664c

feat: add sidebar collapse state persistence and update tests

5ef89f7

feat: enhance accessibility features and update tests for WCAG compli…

0338269

…ance

IEvangelist force-pushed the dapine/tests branch from db1521f to 0338269 Compare April 4, 2026 16:36

IEvangelist added 2 commits April 4, 2026 12:08

feat: add waitForApiSidebarReady helper and update tests for sidebar …

6c6f198

…collapse state persistence

feat: enhance documentation guidelines for custom components and test…

d178787

…ing expectations

IEvangelist commented Apr 5, 2026

View reviewed changes

src/frontend/scripts/update-github-stats.ts Outdated Show resolved Hide resolved

IEvangelist added 7 commits April 4, 2026 21:01

Apply suggestion from @IEvangelist

496934a

feat: add unit tests for FileTree markdown lists in documentation

87f3579

feat: update Hero component to maintain image aspect ratio and add un…

2dbd885

…it test for rendering - fixes #676

feat: update Hero component to use ComponentProps for icon and varian…

fd5afd5

…t types

feat: update frontend build workflow to run all tests and add test:al…

0a70a3b

…l script

feat: enhance type safety and improve sidebar configuration for API r…

ff7dd09

…eference

feat: update lint script to include astro sync for improved consistency

12adf38

IEvangelist enabled auto-merge (squash) April 6, 2026 02:06

JamesNK approved these changes Apr 6, 2026

View reviewed changes

IEvangelist merged commit 2753ba5 into main Apr 6, 2026
5 checks passed

IEvangelist deleted the dapine/tests branch April 6, 2026 03:12

This was referenced Apr 6, 2026

Add TS (or Astro) unit tests #670

Closed

Address lingering feedback from #672 #679

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix frontend e2e sidebar and WCAG regression failures#672

Fix frontend e2e sidebar and WCAG regression failures#672
IEvangelist merged 16 commits intomainfrom
dapine/tests

IEvangelist commented Apr 4, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JamesNK left a comment

Uh oh!

JamesNK Apr 6, 2026

Uh oh!

JamesNK Apr 6, 2026

Uh oh!

JamesNK Apr 6, 2026

Uh oh!

JamesNK Apr 6, 2026

Uh oh!

IEvangelist Apr 6, 2026

Uh oh!

JamesNK Apr 6, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

IEvangelist commented Apr 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What changed

Why

Validation

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JamesNK left a comment

Choose a reason for hiding this comment

Uh oh!

JamesNK Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

JamesNK Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

JamesNK Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

JamesNK Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

IEvangelist Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

JamesNK Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

IEvangelist commented Apr 4, 2026 •

edited

Loading