FD-881: Add local docs build runner and fix Cypress smoke tests

README.md

@@ -113,6 +113,8 @@ If your tests fail, it is because your hook is looking for specific keys in your
 ## E2E Testing
 
 You can run the currently available end-to-end tests with the command `npm run docsTest`.
+This builds docs locally and runs Cypress against the generated output.
+Use `npm run docsTest:deployed` to run the same prerendered docs smoke tests against the GitHub Pages deployment.
 
 ## Bundled spec
 
@@ -143,4 +145,4 @@ Ensure you run `npm run bundle && npm run pretty && npm run redoc` to actually a
 ## Deployment
 The last step is to [create a new release](https://github.com/lob/lob-openapi/releases/new). Create a new tag to match the version you're deploying and provide a brief description. You can monitor the deployment at the [Deploy to Netlify Action](https://github.com/lob/lob-openapi/actions/workflows/deploy.yml).
 
-[Video Tutorial](https://www.notion.so/lob/Deploying-Lob-OpenAPI-Docs-28f349ae90b4498a8b862881db6a834e)
+[Video Tutorial](https://www.notion.so/lob/Deploying-Lob-OpenAPI-Docs-28f349ae90b4498a8b862881db6a834e)

actions/redoc/template.hbs

@@ -773,6 +773,8 @@
     .react-tabs__tab-panel > div > pre > .token.string, .react-tabs__tab-panel > div > pre > .token.builtin{color:#416581}
     .react-tabs__tab-panel > div > pre > .token.operator,
     .react-tabs__tab-panel > div > pre > .token.variable{color:#324350}
+    pre > code[class*='language-'],
+    pre > code[class*='language-'] * { color:#000000 !important;text-shadow:none !important }
     div.react-tabs__tab-panel.react-tabs__tab-panel--selected{border-radius:10px}
 
     {{!-- sidebars fontweight --}}

cypress/e2e/links_test.cy.js

@@ -1,9 +1,6 @@
 describe("ensures introduction links and text are valid", () => {
-  // This link leads to the staging docs which are built off main right now.
-  // We will change it to the live docs after a new release is created, since
-  // some things used in the tests––like the ID––aren't live yet.
   beforeEach(() => {
-    cy.visit("https://lob.github.io/lob-openapi/");
+    cy.visitDocs();
   });
 
   it("contains a link to the main Lob page", () => {
@@ -71,8 +68,8 @@ describe("ensures introduction links and text are valid", () => {
   });
 
   it("contains the test & live environments link", () => {
-    cy.get("h1")
-      .contains("Test and Live Environments")
+    cy.get('[data-section-id="tag/Test-and-Live-Environments"]')
+      .contains("h2", "Test and Live Environments")
       .find("a")
       .should("have.attr", "href")
       .and("include", "#tag/Test-and-Live-Environments");

cypress/e2e/style_test.cy.js

@@ -1,14 +1,44 @@
 describe("ensures CSS styling is valid", () => {
   beforeEach(() => {
-    cy.visit("https://lob.github.io/lob-openapi/");
+    cy.visitDocs();
   });
 
-  it("uses the right font for the feedback button", () => {
-    // makes sure the lob.com link goes to the right page
+  it("uses the right font for the Lob brand link", () => {
     cy.get('a[id="lob-link"]').should(
       "have.css",
       "font-family",
       "Larsseit, sans-serif"
     );
   });
+
+  it("uses the configured light background for request samples", () => {
+    cy.contains("h3", "Request samples")
+      .parents()
+      .then(($parents) => {
+        const hasLightPanel = [...$parents].some(
+          (element) =>
+            getComputedStyle(element).backgroundColor === "rgb(247, 249, 250)"
+        );
+
+        expect(hasLightPanel).to.eq(true);
+      });
+  });
+});
+
+describe("ensures Redoc runtime is valid", () => {
+  it("hydrates generated docs without runtime errors", () => {
+    const uncaughtErrors = [];
+
+    cy.on("uncaught:exception", (error) => {
+      uncaughtErrors.push(error.message);
+      return false;
+    });
+
+    cy.visitDocs({ hydrate: true });
+
+    cy.window().should((win) => {
+      expect(win.Redoc?.hydrate?.toString()).not.to.eq("function() {}");
+      expect(uncaughtErrors).to.deep.eq([]);
+    });
+  });
 });

cypress/support/commands.js

@@ -1,25 +1,22 @@
-// ***********************************************
-// This example commands.js shows you how to
-// create various custom commands and overwrite
-// existing commands.
-//
-// For more comprehensive examples of custom
-// commands please read more here:
-// https://on.cypress.io/custom-commands
-// ***********************************************
-//
-//
-// -- This is a parent command --
-// Cypress.Commands.add('login', (email, password) => { ... })
-//
-//
-// -- This is a child command --
-// Cypress.Commands.add('drag', { prevSubject: 'element'}, (subject, options) => { ... })
-//
-//
-// -- This is a dual command --
-// Cypress.Commands.add('dismiss', { prevSubject: 'optional'}, (subject, options) => { ... })
-//
-//
-// -- This will overwrite an existing command --
-// Cypress.Commands.overwrite('visit', (originalFn, url, options) => { ... })
+const DEPLOYED_DOCS_URL = "https://lob.github.io/lob-openapi/";
+const SEGMENT_SCRIPT_URL = "https://cdn.segment.com/**";
+const REDOCLY_SCRIPT_URL =
+  "https://cdn.redocly.com/redoc/**/redoc.standalone.js";
+
+Cypress.Commands.add("visitDocs", ({ hydrate = false } = {}) => {
+  // These smoke tests validate prerendered docs content and styles. Keep
+  // analytics inert so failures are tied to docs content changes.
+  cy.intercept("GET", SEGMENT_SCRIPT_URL, {
+    headers: { "content-type": "text/javascript" },
+    body: "",
+  });
+
+  if (!hydrate) {
+    cy.intercept("GET", REDOCLY_SCRIPT_URL, {
+      headers: { "content-type": "text/javascript" },
+      body: "window.Redoc = { hydrate: function() {} };",
+    });
+  }
+
+  cy.visit(Cypress.env("docsUrl") || DEPLOYED_DOCS_URL);
+});