Skip to Content

Testing SEO Metadata and Structured Data

Test SEO fixtures and inspect graph validation diagnostics.

@puzzle-ui/seo includes framework-independent helpers for testing graphs and metadata in your existing test runner.

Install

npm install @puzzle-ui/seo react

React 19 is a peer dependency. Framework adapters do not require a framework package at runtime.

Quick start

import { assertSeoTest, createSeoTestFixture } from "@puzzle-ui/seo/testing";

const fixture = createSeoTestFixture({
  config: { siteUrl: "https://example.com" },
  nodes: [{ "@type": "Organization", name: "Example" }],
  metadata: { title: "Welcome to Example", description: "Discover the Example website and its services.", canonical: "https://example.com/" },
});
assertSeoTest(fixture, { strict: true });

A fixture requires config.siteUrl and accepts nodes or graph, but not both, plus optional metadata. createSeoTestFixture builds a graph from nodes. assertSeoTest returns a result or throws formatted diagnostics; runSeoTest returns the result without throwing.

Test options and inspection

NameTypeDefaultDescription
strictbooleanfalseUse strict validation instead of warn mode.
validateSchemabooleantrueInclude schema issues in the test result.
validateMetadatabooleantrueInclude metadata validation.
validateReferencesbooleantrueInclude unresolved-reference issues.
import { formatSeoDiagnostics, inspectSeoGraph, runSeoTest } from "@puzzle-ui/seo/testing";

const result = runSeoTest(fixture);
console.log(formatSeoDiagnostics(result.report));
if (fixture.graph) {
  const inspection = inspectSeoGraph(fixture.graph, { baseUrl: "https://example.com" });
  console.log(inspection.typeCounts, inspection.unresolvedReferences);
}

The result has passed, errors, warnings, and a filtered report. Inspection also includes node count, node IDs and types, properties, references and validity. Diagnostic formatting accepts includeSuggestions, includePaths, and includeSummary, all enabled by default. Keep checks enabled unless a test intentionally isolates a particular concern.

Exports

@puzzle-ui/seo/testing exports createSeoTestFixture, runSeoTest, assertSeoTest, inspectSeoGraph, formatSeoDiagnostics, and fixture, result, inspection and formatting types.