From cd0c7863befa2f4467372e7d0da2e118e60bf0ac Mon Sep 17 00:00:00 2001
From: Ali Waseem <waseema393@gmail.com>
Date: Fri, 31 Jul 2026 14:35:27 -0600
Subject: [PATCH] test(docs): run the fixed reference checks on harness-only
 changes

A pull request touching only e2e/docs resolved to no pages and skipped
Playwright entirely, so changes to the suite were never exercised by it.
reference-pages.spec.ts uses a fixed page list and has something to run
for those changes, so treat the harness and the workflow as in scope.
---
 .github/workflows/docs-e2e.yml       |  3 ++-
 e2e/docs/utils/resolve-docs-scope.ts | 13 ++++++++-----
 2 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/docs-e2e.yml b/.github/workflows/docs-e2e.yml
index 0ba709f1dd5..0d5f03a7f24 100644
--- a/.github/workflows/docs-e2e.yml
+++ b/.github/workflows/docs-e2e.yml
@@ -73,7 +73,8 @@ jobs:
           node-version-file: '.nvmrc'
 
       # Map changed owned content (guides, troubleshooting, partials) to page
-      # URLs. Harness-only PRs resolve to skip=true and exit before Playwright.
+      # URLs. Reference and harness changes resolve to no pages but still run,
+      # for the fixed set in reference-pages.spec.ts.
       - name: Resolve docs E2E scope
         id: scope
         env:
diff --git a/e2e/docs/utils/resolve-docs-scope.ts b/e2e/docs/utils/resolve-docs-scope.ts
index e1ba77fc2b3..a46e8b3047d 100644
--- a/e2e/docs/utils/resolve-docs-scope.ts
+++ b/e2e/docs/utils/resolve-docs-scope.ts
@@ -96,15 +96,18 @@ function isHiddenMdx(filePath: string): boolean {
 }
 
 /**
- * Files behind the pages features/reference-pages.spec.ts loads. It uses a
- * fixed list, so a change here runs Playwright even with no guide pages.
+ * Changes that should run Playwright even when no guide pages resolve, since
+ * features/reference-pages.spec.ts uses a fixed page list: the sources behind
+ * the reference pages, and the harness that loads them.
  */
-function isReferenceRelevantFile(filePath: string): boolean {
+function runsFixedChecks(filePath: string): boolean {
   const path = normalizeRepoPath(filePath)
   return (
     path.startsWith('apps/docs/spec/') ||
     path.startsWith('apps/docs/features/docs/Reference') ||
-    path === 'apps/docs/middleware.ts'
+    path === 'apps/docs/middleware.ts' ||
+    path.startsWith('e2e/docs/') ||
+    path === '.github/workflows/docs-e2e.yml'
   )
 }
 
@@ -320,7 +323,7 @@ export async function resolveDocsScope(
 
   return {
     pages: sorted.slice(0, maxPages),
-    skip: sorted.length === 0 && !options.changedFiles.some(isReferenceRelevantFile),
+    skip: sorted.length === 0 && !options.changedFiles.some(runsFixedChecks),
   }
 }