Format fixture snapshots as markdown

.prettierignore

@@ -16,3 +16,4 @@ examples/incremental-migration/schemas/gratsGeneratedSchema.ts
 # Local Netlify folder
 .netlify
 website/src/workers/ts.worker.mjs
+*.expected.md

src/tests/Markdown.ts

@@ -0,0 +1,49 @@
+type MarkdownSection =
+  | {
+      kind: "header";
+      level: number;
+      content: string;
+    }
+  | {
+      kind: "codeBlock";
+      content: string;
+      fileType: string;
+      fileName?: string;
+    };
+
+export class Markdown {
+  sections: MarkdownSection[] = [];
+
+  addHeader(level: number, content: string) {
+    this.sections.push({ kind: "header", level, content });
+  }
+
+  addCodeBlock(content: string, fileType: string, fileName?: string) {
+    this.sections.push({ kind: "codeBlock", content, fileType, fileName });
+  }
+
+  addMarkdown(markdown: Markdown) {
+    for (const section of markdown.sections) {
+      this.sections.push(section);
+    }
+  }
+
+  toString(): string {
+    let output = "";
+    for (const section of this.sections) {
+      switch (section.kind) {
+        case "header":
+          output += `${"#".repeat(section.level)} ${section.content}\n\n`;
+          break;
+        case "codeBlock": {
+          const fileNamePart = section.fileName
+            ? ` title="${section.fileName}"`
+            : "";
+          output += `\`\`\`${section.fileType}${fileNamePart}\n${section.content.trimEnd()}\n\`\`\`\n\n`;
+          break;
+        }
+      }
+    }
+    return output.trim();
+  }
+}

src/tests/TestRunner.ts

@@ -3,11 +3,14 @@ import * as path from "path";
 import { diff } from "jest-diff";
 import { ask } from "./yesNo";
 import { Result } from "../utils/Result";
+import { Markdown } from "./Markdown";
 
-type Transformer = (
+export type TransformerResult = Result<Markdown, Markdown> | false;
+
+export type Transformer = (
   code: string,
-  filename: string,
-) => Promise<Result<string, string> | false> | (Result<string, string> | false);
+  fileName: string,
+) => TransformerResult | Promise<TransformerResult>;
 
 /**
  * Looks in a fixtures dir for .ts files, transforms them according to the
@@ -86,7 +89,7 @@ export default class TestRunner {
     fixture: string,
     { interactive }: { interactive: boolean },
   ) {
-    const expectedFileName = fixture + ".expected";
+    const expectedFileName = fixture + ".expected.md";
     const expectedFilePath = path.join(this._fixturesDir, expectedFileName);
     if (this._otherFiles.has(expectedFileName)) {
       this._otherFiles.delete(expectedFileName);
@@ -116,14 +119,19 @@ export default class TestRunner {
         ? transformResult.value
         : transformResult.err;
 
-    const testOutput = `-----------------
-INPUT
------------------ 
-${fixtureContent}
------------------
-OUTPUT
------------------
-${actualOutput}`;
+    const fileType = path.extname(fixture).slice(1);
+
+    const output = new Markdown();
+    output.addHeader(2, "input");
+    output.addCodeBlock(fixtureContent, fileType, fixture);
+    output.addHeader(2, "Output");
+    if (actualOutput instanceof Markdown) {
+      output.addMarkdown(actualOutput);
+    } else {
+      output.addCodeBlock(actualOutput, "");
+    }
+
+    const testOutput = output.toString();
 
     // Validate naming convention: .invalid files should have errors, others should succeed
     const isInvalidTest = fixture.includes(".invalid.");
@@ -177,10 +185,7 @@ ${actualOutput}`;
     }
   }
 
-  async transform(
-    code: string,
-    filename: string,
-  ): Promise<Result<string, string> | false> {
+  async transform(code: string, filename: string): Promise<TransformerResult> {
     try {
       return await this._transformer(code, filename);
     } catch (e) {

src/tests/configParserFixtures/empty.json.expected.md

@@ -0,0 +1,26 @@
+## input
+
+```json title="empty.json"
+{}
+```
+
+## Output
+
+### Parsed Config
+
+```json
+{
+  "graphqlSchema": "./schema.graphql",
+  "tsSchema": "./schema.ts",
+  "tsClientEnums": null,
+  "nullableByDefault": true,
+  "strictSemanticNullability": false,
+  "reportTypeScriptTypeErrors": false,
+  "schemaHeader": "# Schema generated by Grats (https://grats.capt.dev)\n# Do not manually edit. Regenerate by running `npx grats`.",
+  "tsSchemaHeader": "/**\n * Executable schema generated by Grats (https://grats.capt.dev)\n * Do not manually edit. Regenerate by running `npx grats`.\n */",
+  "tsClientEnumsHeader": "/**\n * TypeScript enum definitions generated by Grats (https://grats.capt.dev)\n * Do not manually edit. Regenerate by running `npx grats`.\n */",
+  "importModuleSpecifierEnding": "",
+  "EXPERIMENTAL__emitMetadata": false,
+  "EXPERIMENTAL__emitResolverMap": false
+}
+```

src/tests/configParserFixtures/experimentalField.json.expected.md

@@ -0,0 +1,34 @@
+## input
+
+```json title="experimentalField.json"
+{
+  "EXPERIMENTAL__emitMetadata": true
+}
+```
+
+## Output
+
+### Parsed Config
+
+```json
+{
+  "graphqlSchema": "./schema.graphql",
+  "tsSchema": "./schema.ts",
+  "tsClientEnums": null,
+  "nullableByDefault": true,
+  "strictSemanticNullability": false,
+  "reportTypeScriptTypeErrors": false,
+  "schemaHeader": "# Schema generated by Grats (https://grats.capt.dev)\n# Do not manually edit. Regenerate by running `npx grats`.",
+  "tsSchemaHeader": "/**\n * Executable schema generated by Grats (https://grats.capt.dev)\n * Do not manually edit. Regenerate by running `npx grats`.\n */",
+  "tsClientEnumsHeader": "/**\n * TypeScript enum definitions generated by Grats (https://grats.capt.dev)\n * Do not manually edit. Regenerate by running `npx grats`.\n */",
+  "importModuleSpecifierEnding": "",
+  "EXPERIMENTAL__emitMetadata": true,
+  "EXPERIMENTAL__emitResolverMap": false
+}
+```
+
+### Warnings
+
+```text
+Grats: The `EXPERIMENTAL__emitMetadata` option is experimental and will be renamed or removed in a future release.
+```

src/tests/configParserFixtures/invlaidKey.invalid.json.expected.md

@@ -0,0 +1,15 @@
+## input
+
+```json title="invlaidKey.invalid.json"
+{
+  "lol": true
+}
+```
+
+## Output
+
+### Error Report
+
+```text
+error: Unknown Grats config option `lol`.
+```

src/tests/configParserFixtures/multiLineHeader.json.expected.md

@@ -0,0 +1,28 @@
+## input
+
+```json title="multiLineHeader.json"
+{
+  "schemaHeader": ["/**", " * An amazing GraphQL schema", " */"]
+}
+```
+
+## Output
+
+### Parsed Config
+
+```json
+{
+  "graphqlSchema": "./schema.graphql",
+  "tsSchema": "./schema.ts",
+  "tsClientEnums": null,
+  "nullableByDefault": true,
+  "strictSemanticNullability": false,
+  "reportTypeScriptTypeErrors": false,
+  "schemaHeader": "/**\n * An amazing GraphQL schema\n */",
+  "tsSchemaHeader": "/**\n * Executable schema generated by Grats (https://grats.capt.dev)\n * Do not manually edit. Regenerate by running `npx grats`.\n */",
+  "tsClientEnumsHeader": "/**\n * TypeScript enum definitions generated by Grats (https://grats.capt.dev)\n * Do not manually edit. Regenerate by running `npx grats`.\n */",
+  "importModuleSpecifierEnding": "",
+  "EXPERIMENTAL__emitMetadata": false,
+  "EXPERIMENTAL__emitResolverMap": false
+}
+```

src/tests/configParserFixtures/multiLineNonHeader.invalid.json.expected.md

@@ -0,0 +1,15 @@
+## input
+
+```json title="multiLineNonHeader.invalid.json"
+{
+  "tsSchema": ["/path/", "to/", "schema.ts"]
+}
+```
+
+## Output
+
+### Error Report
+
+```text
+error: Expected property `tsSchema` to be a string, but got ["/path/","to/","schema.ts"].
+```

src/tests/configParserFixtures/nonNullableFieldIsNull.invalid.json.expected.md

@@ -0,0 +1,15 @@
+## input
+
+```json title="nonNullableFieldIsNull.invalid.json"
+{
+  "importModuleSpecifierEnding": null
+}
+```
+
+## Output
+
+### Error Report
+
+```text
+error: The Grats config option `importModuleSpecifierEnding` must be a `string` if provided.
+```