mirror of https://github.com/theNewDynamic/gohugo-theme-ananke.git

Patrick Kollitsch
13 hours ago e5bbb4b585642ac93a18a605714ddae3277a0b82
test(catalog): record the documentation page of each feature

Add an optional docs path to tests/catalog.yaml entries and fill it for
all 17 parameters and 4 shortcodes. The coverage gate checks that a
docs value is a site-relative path on the documentation site; it does
not require one. Two unit tests cover a valid and an invalid path.

Signed-off-by: Patrick Kollitsch <davidsneighbourdev+gh@gmail.com>
3 files modified
49 ■■■■■ changed files
tests/catalog.yaml 24 ●●●●● patch | view | raw | blame | history
tests/coverage-gate.mjs 9 ●●●●● patch | view | raw | blame | history
tests/unit/coverage-gate.test.mjs 16 ●●●●● patch | view | raw | blame | history
tests/catalog.yaml
@@ -5,52 +5,76 @@
# fails. This forces a test to accompany each new or changed feature.
#
# `tests` entries must name existing executable spec or quickstart files.
# `docs` names the documentation page as a site-relative path on
# https://ananke-documentation.netlify.app. The gate checks only its
# format.
# This checks registration and paths, not whether assertions cover every behaviour.
params:
  ananke.responsive_image_widths:
    docs: "/configuration/reference/#general-options"
    tests: ["tests/e2e/responsive-header.spec.ts"]
  ananke.show_recent_posts:
    docs: "/configuration/reference/#general-options"
    tests: ["scripts/test-hugo-quickstart.ts"]
  ananke.show_categories:
    docs: "/configuration/reference/#general-options"
    tests: ["scripts/test-hugo-quickstart.ts"]
  ananke.copy_code:
    docs: "/configuration/reference/#general-options"
    tests:
      - "tests/e2e/copy-button.spec.ts"
      - "tests/fixtures/copy-code/copy-code.test.mjs"
  ananke.navigation.submenu_mode:
    docs: "/configuration/reference/#header-and-navigation"
    tests: ["tests/e2e/navigation-modes.spec.ts"]
  ananke.navigation.classes.nav:
    docs: "/configuration/reference/#header-and-navigation"
    tests: ["tests/e2e/navigation.spec.ts"]
  ananke.navigation.classes.inner:
    docs: "/configuration/reference/#header-and-navigation"
    tests: ["tests/e2e/navigation.spec.ts"]
  ananke.navigation.classes.brand:
    docs: "/configuration/reference/#header-and-navigation"
    tests: ["tests/e2e/navigation.spec.ts"]
  ananke.navigation.classes.toggle:
    docs: "/configuration/reference/#header-and-navigation"
    tests: ["tests/e2e/navigation.spec.ts"]
  ananke.navigation.classes.group:
    docs: "/configuration/reference/#header-and-navigation"
    tests: ["tests/e2e/header.spec.ts"]
  ananke.navigation.classes.panel:
    docs: "/configuration/reference/#header-and-navigation"
    tests: ["tests/e2e/navigation.spec.ts"]
  ananke.navigation.classes.menu:
    docs: "/configuration/reference/#header-and-navigation"
    tests: ["tests/e2e/navigation.spec.ts"]
  ananke.navigation.classes.item:
    docs: "/configuration/reference/#header-and-navigation"
    tests: ["tests/e2e/navigation.spec.ts"]
  ananke.navigation.classes.link:
    docs: "/configuration/reference/#header-and-navigation"
    tests: ["tests/e2e/navigation.spec.ts"]
  ananke.navigation.classes.submenu_toggle:
    docs: "/configuration/reference/#header-and-navigation"
    tests: ["tests/e2e/navigation.spec.ts"]
  ananke.navigation.classes.submenu:
    docs: "/configuration/reference/#header-and-navigation"
    tests: ["tests/e2e/navigation.spec.ts"]
  ananke.navigation.classes.submenu_link:
    docs: "/configuration/reference/#header-and-navigation"
    tests: ["tests/e2e/navigation.spec.ts"]
shortcodes:
  edit-page:
    docs: "/content/shortcodes/edit-page/"
    tests: ["tests/e2e/shortcodes.spec.ts"]
  form-contact:
    docs: "/content/shortcodes/contact-form/"
    tests: ["tests/e2e/shortcodes.spec.ts"]
  page-index:
    docs: "/content/shortcodes/#page-index"
    tests: ["tests/e2e/shortcodes.spec.ts"]
  since:
    docs: "/content/shortcodes/since/"
    tests: ["tests/e2e/shortcodes.spec.ts"]
tests/coverage-gate.mjs
@@ -8,6 +8,9 @@
 *   - every shortcode in layouts/_shortcodes/
 * must appear in tests/catalog.yaml with a non-empty `tests` list.
 *
 * An optional `docs` value names the documentation page of the feature as a
 * site-relative path; it is checked for format only.
 *
 * It also reports catalog entries that no longer match a real param/shortcode
 * (stale entries), so the catalog stays in sync as features are added, renamed,
 * or removed.
@@ -78,9 +81,15 @@
const catParams = catalogued(catalog.params);
const catShortcodes = catalogued(catalog.shortcodes);
const DOCS_PATH = /^\/(?:[a-z0-9-]+\/)*(?:#[a-z0-9-]+)?$/;
const errors = [];
for (const section of [catalog.params, catalog.shortcodes]) {
  for (const [feature, entry] of Object.entries(section || {})) {
    // Optional documentation target: a site-relative path on the
    // documentation site, for example "/configuration/reference/#homepage".
    if (entry?.docs !== undefined && !DOCS_PATH.test(String(entry.docs))) {
      errors.push(`${feature}: invalid docs path '${entry.docs}'`);
    }
    for (const ref of entry?.tests || []) {
      if (typeof ref !== "string") {
        errors.push(`${feature}: test reference must be a path string`);
tests/unit/coverage-gate.test.mjs
@@ -11,6 +11,7 @@
  shortcode = false,
  reference = "tests/e2e/example.spec.ts",
  makeTest = true,
  docs = "",
} = {}) {
  const root = mkdtempSync(join(tmpdir(), "ananke-coverage-gate-"));
  const write = (file, content) => {
@@ -24,7 +25,7 @@
    );
    write(
      "tests/catalog.yaml",
      `params:\n  ananke.existing:\n    tests: ["${reference}"]\n`,
      `params:\n  ananke.existing:\n    tests: ["${reference}"]\n${docs ? `    docs: "${docs}"\n` : ""}`,
    );
    mkdirSync(join(root, "layouts/_shortcodes"), { recursive: true });
    if (shortcode) write("layouts/_shortcodes/new.html", "<p>new</p>");
@@ -65,3 +66,16 @@
  assert.equal(result.status, 1);
  assert.match(result.stderr, /ananke.navigation.new.*has no test/);
});
test("a documentation path passes", () => {
  assert.equal(
    runFixture({ docs: "/configuration/reference/#homepage" }).status,
    0,
  );
});
test("an invalid documentation path fails", () => {
  const result = runFixture({ docs: "https://example.com/page" });
  assert.equal(result.status, 1);
  assert.match(result.stderr, /invalid docs path/);
});