test: add characterization tests for DocsMarkedRenderer (#19413)

These tests are meant to simply document and verify the existing
behavior of the DocsMarkedRenderer. They aren't necessarily meant to be
a good example of unit testing best-practices.

A characterization test "is a means to describe (characterize) the actual behavior of an existing piece of software, and therefore protect existing behavior of legacy code against unintended changes via automated testing."
https://en.wikipedia.org/wiki/Characterization_test

Author: atscott

tools/markdown-to-html/BUILD.bazel

@@ -1,11 +1,16 @@
 load("@build_bazel_rules_nodejs//:index.bzl", "nodejs_binary")
-load("//tools:defaults.bzl", "ts_library")
+load("//tools:defaults.bzl", "jasmine_node_test", "ts_library")
 
 package(default_visibility = ["//visibility:public"])
 
 ts_library(
     name = "transform-markdown",
-    srcs = glob(["**/*.ts"]),
+    srcs = glob(
+        ["**/*.ts"],
+        exclude = [
+            "*.spec.ts",
+        ],
+    ),
     tsconfig = ":tsconfig.json",
     deps = [
         "//tools/highlight-files:sources",
@@ -23,3 +28,26 @@ nodejs_binary(
     ],
     entry_point = ":transform-markdown.ts",
 )
+
+ts_library(
+    name = "unit_test_lib",
+    testonly = True,
+    srcs = glob(
+        ["*.spec.ts"],
+    ),
+    tsconfig = ":tsconfig.json",
+    visibility = ["//visibility:private"],
+    deps = [
+        ":transform-markdown",
+        "@npm//@types/jasmine",
+        "@npm//@types/node",
+        "@npm//marked",
+        "@npm//typescript",
+    ],
+)
+
+jasmine_node_test(
+    name = "unit_tests",
+    srcs = [":unit_test_lib"],
+    visibility = ["//visibility:private"],
+)

tools/markdown-to-html/docs-marked-renderer.spec.ts

@@ -0,0 +1,97 @@
+import {DocsMarkdownRenderer} from './docs-marked-renderer';
+
+describe('DocsMarkdownRenderer', () => {
+  let renderer: DocsMarkdownRenderer;
+  beforeEach(() => {
+    renderer = new DocsMarkdownRenderer();
+  });
+
+  it('generates regular headings for h1 and h2', () => {
+    expect(renderer.heading('a', 1, 'ignored')).toEqual('<h1>a</h1>');
+    expect(renderer.heading('b', 2, 'ignored')).toEqual('<h2>b</h2>');
+  });
+
+  it('creates header link for h3 and h4 headings', () => {
+    const heading3 = renderer.heading('heading text', 3, 'link-id');
+    expectEqualIgnoreLeadingWhitespace(heading3, `
+        <h3 id="link-id" class="docs-header-link">
+          <span header-link="link-id"></span>
+          heading text
+        </h3>
+      `);
+    const heading4 = renderer.heading('heading text', 4, 'second-link-id');
+    expectEqualIgnoreLeadingWhitespace(heading4, `
+        <h4 id="second-link-id" class="docs-header-link">
+          <span header-link="second-link-id"></span>
+          heading text
+        </h4>
+      `);
+  });
+
+  it('handles duplicate ids for headings', () => {
+    expect(renderer.heading('first', 3, 'id')).toContain('id="id"');
+    expect(renderer.heading('second', 3, 'id')).toContain('id="id-1"');
+  });
+
+  it('generates links', () => {
+    expect(renderer.link('something', 'some title', 'some text'))
+        .toEqual('<a href="guide/something" title="some title">some text</a>');
+    expect(renderer.link('guide/something', 'some title', 'some text'))
+        .toEqual('<a href="guide/something" title="some title">some text</a>');
+    expect(renderer.link('#some-hash', 'some title', 'some text'))
+        .toEqual('<a href="#some-hash" title="some title">some text</a>');
+    expect(renderer.link('http://google.com', 'some title', 'some text'))
+        .toEqual('<a href="http://google.com" title="some title">some text</a>');
+  });
+
+  it('generates html using new API', () => {
+    const result = renderer.html(`<!-- example(
+         {
+          "example": "exampleName",
+          "file": "example-html.html",
+          "region": "some-region",
+         }
+        ) -->`);
+
+    // TODO(annieyw): I think DocsMarkedRenderer#html needs to be fixed for the new API?
+    expectEqualIgnoreLeadingWhitespace(result, `<div material-docs-example="
+         {
+          "example": "exampleName",
+          "file": "example-html.html",
+          "region": "some-region",
+         }
+        "></div>`);
+  });
+
+  it('generates html using old API', () => {
+    expect(renderer.html('<!-- example(name) -->'))
+        .toEqual('<div material-docs-example="name"></div>');
+  });
+
+  it('allows id links with matching id element', () => {
+    let output = renderer.link('#my-id', 'link title', 'link text');
+    output += renderer.heading('heading text', 3, 'my-id');
+    const result = renderer.finalizeOutput(output, 'filename.html');
+    expect(result).toEqual(jasmine.stringMatching(/<div class="docs-markdown"/));
+  });
+
+  it('does not allow id links with no matching id element', () => {
+    spyOn(console, 'error');
+    spyOn(process, 'exit');
+    let output = renderer.link('#my-id', 'link title', 'link text');
+    renderer.finalizeOutput(output, 'filename.html');
+    expect((console.error as jasmine.Spy).calls.allArgs()).toEqual([
+      [jasmine.stringMatching(/Could not process file: filename.html.*/)],
+      [jasmine.stringMatching(/.*Found link to "my-id". This heading does not exist./)]
+    ]);
+    expect(process.exit).toHaveBeenCalledWith(1);
+  });
+
+  function expectEqualIgnoreLeadingWhitespace(actual: string, expected: string) {
+    expect(stripLeadingWhitespace(actual)).toEqual(stripLeadingWhitespace(expected));
+  }
+
+  function stripLeadingWhitespace(s: string) {
+    return s.replace(/^\s*/gm, '');
+  }
+});

tools/markdown-to-html/tsconfig.json

@@ -4,8 +4,14 @@
     "module": "commonjs",
     "target": "es5",
     "sourceMap": true,
-    "types": ["node"]
+    "types": [
+      "jasmine",
+      "node"
+    ]
   },
+  "exclude": [
+    "*.spec.ts",
+  ],
   "bazelOptions": {
     "suppressTsconfigOverrideWarnings": true
   }