Skip to content

EDU-18161: make documentation page sampling deterministic#1249

Open
PedroAntunesCosta wants to merge 17 commits intomainfrom
fix/edu-18161-deterministic-doc-sampling
Open

EDU-18161: make documentation page sampling deterministic#1249
PedroAntunesCosta wants to merge 17 commits intomainfrom
fix/edu-18161-deterministic-doc-sampling

Conversation

@PedroAntunesCosta
Copy link
Copy Markdown
Contributor

@PedroAntunesCosta PedroAntunesCosta commented May 5, 2026

Summary

Make the documentation page status sampling deterministic, show reviewers exactly which pages were tested, and reduce avoidable Cypress runtime in the sampled docs check.

Changes

  • replace Math.random-based page selection with a seeded PRNG in the sampler
  • keep public/navigation.json as the single navigation source for these Cypress workflows
  • persist sampled page metadata and render it in the PR summary comment
  • add an End-to-end tests heading and move the Sampled pages section to the bottom of the comment
  • wire SAMPLE_SEED into the integration and extensive workflows
  • stop retrying every docs-status failure indiscriminately and retry only transient infrastructure HTTP responses
  • replace the fixed 2 second post-visit delay with a targeted sidebar readiness check
  • keep the sampled page set reproducible while still letting each pushed commit generate its own traceable seed

Why

The tests-summary PR comment was hard to trust because identical inputs could sample different pages and the workflows were wired to two different navigation sources. On top of that, the documentation pages status spec could spend hours retrying content failures and sleeping on every visited page. These changes make reruns reproducible for the same seed, show the sampled page list directly in the comment, and reduce avoidable runtime in the longest Cypress step.

Related Task

EDU-18161

@PedroAntunesCosta PedroAntunesCosta added bug Something isn't working release-no No release bump labels May 5, 2026
@PedroAntunesCosta PedroAntunesCosta self-assigned this May 5, 2026
@netlify
Copy link
Copy Markdown

netlify Bot commented May 5, 2026

Deploy Preview for elated-hoover-5c29bf ready!

Name Link
🔨 Latest commit b1c0e87
🔍 Latest deploy log https://app.netlify.com/projects/elated-hoover-5c29bf/deploys/69fe55c541a0d000088313fc
😎 Deploy Preview https://deploy-preview-1249--elated-hoover-5c29bf.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 5, 2026

Performance Results

Page /

Performance
Accessibility
Best Practices
SEO

Complete results here

Page /docs/guides/tax-services-specification

Performance
Accessibility
Best Practices
SEO

Complete results here

Page /docs/guides/creating-a-regular-order-from-an-existing-cart

Performance
Accessibility
Best Practices
SEO

Complete results here

Page /docs/api-reference/buyer-organizations

Performance
Accessibility
Best Practices
SEO

Complete results here

Page /docs/api-reference/buyer-organizations#post-/api/b2b/import/buyer-orgs/validate/-importId-

Performance
Accessibility
Best Practices
SEO

Complete results here

Page /docs/api-reference/search-api

Performance
Accessibility
Best Practices
SEO

Complete results here

Page /docs/api-reference/search-api#get-/api/catalog_system/pub/facets/search/-term-

Performance
Accessibility
Best Practices
SEO

Complete results here

Page /docs/guides/vtex-io-documentation-builder-version-statuses

Performance
Accessibility
Best Practices
SEO

Complete results here

Page /docs/guides/vtex-io-documentation-design-guidelines

Performance
Accessibility
Best Practices
SEO

Complete results here

Page /docs/apps/vtex.badges

Performance
Accessibility
Best Practices
SEO

Complete results here

Page /docs/apps/vtex.reviews-and-ratings

Performance
Accessibility
Best Practices
SEO

Complete results here

Page /docs/guides/faststore/storefront-features-handling-third-party-scripts

Performance
Accessibility
Best Practices
SEO

Complete results here

Page /docs/guides/vtex-io-documentation-internationalizing-product-prices

Performance
Accessibility
Best Practices
SEO

Complete results here

Page /docs/troubleshooting/the-price-in-the-shelf-or-in-the-search-results-is-different-from-the-product-page

Performance
Accessibility
Best Practices
SEO

Complete results here

Page /docs/troubleshooting/i-cant-publish-my-theme-due-to-app-dependency

Performance
Accessibility
Best Practices
SEO

Complete results here

Page /updates/release-notes/sum-of-installments-without-interest-on-search-results-page

Performance
Accessibility
Best Practices
SEO

Complete results here

Page /updates/release-notes/2024-12-19-new-feature-available-for-anti-fraud-providers-gift-card-transaction-analysis

Performance
Accessibility
Best Practices
SEO

Complete results here

Overall Performance

Performance
Accessibility
Best Practices
SEO

@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 6, 2026

End-to-end tests

Content regressions

2 tests failed:

api-guides

2 failing tests:

  • try to send feedback
  • try to click on the last element of table of contents

Preview infrastructure

No infrastructure failures.

Other

None.

For more information, open the cypress action summary page.

PedroAntunesCosta and others added 14 commits May 6, 2026 12:11
Each failed test now emits a JSON line to cypress-failures.jsonl
with spec, title, attempt, type, and message fields instead of a
plain-text line in cypress.log. All callers updated accordingly.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
summary-report.js now reads cypress-failures.jsonl, groups records
by spec and title, and reports the number of unique failing tests
regardless of how many times each was retried. A (retried Nx) suffix
is shown when a test was attempted more than once.

Workflow files updated to preserve, merge, and clean up
cypress-failures.jsonl instead of the old cypress.log.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…spec

Replace the expect() status assertion with a conditional that sets a
failureType flag (http / load_timeout / dom) before the potentially
failing command. afterEach reads the flag so writeLog emits the correct
type for each failure rather than always emitting 'dom'.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
summary-report.js now renders three sections:
- Content regressions (type=dom) — drives the headline count
- Preview infrastructure (type=http/load_timeout) — visible but not
  counted in the headline, each entry shows the status code or timeout
- Other — defensive bucket for unrecognised types

The headline "N tests failed" now reflects only actionable content
failures. Infrastructure noise is surfaced separately so reviewers
can distinguish flaky preview from real broken pages.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
load_timeout entries had no explanation in the Preview infrastructure
section. Now falls back to the type name (e.g. "load timeout") so
reviewers always know why a failure was classified as infrastructure.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
When the Cypress component tests crash (not just test failures), no
cypress-failures.jsonl is written. Previously the report ran with an
empty input and published "All tests were successful!" which is wrong.

Now the report only runs when failure records exist OR the component
test step actually completed successfully. A Cypress crash instead
publishes a "failed to run" message.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Without a timeout, the integration tests can run for GitHub's full 6-hour
job limit (e.g. when the sampled pages include many slow API reference pages),
preventing the summary report step from ever executing.
…pages section

- Surface the sample seed in the top-level H1 so it's immediately visible
- Content regressions / Preview infrastructure / Other sections are always
  rendered; each falls back to a "none" line when the bucket is empty
- Sampled pages list remains at the bottom of the comment
- Remove the now-inlined printSampleMetadata helper
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working release-no No release bump

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant