{"fileId":"664d362ac4aa0dc46f5f868d795c6aa0e75acc9cf7c351fc7445bbb7cc28c841","type":"Contented","path":"/jest/pipelines/jest-markdown","modifiedDate":1696943516077,"sections":["Pipelines"],"fields":{"title":"Jest Markdown Pipeline","description":"\"Nothing is better than documentation with examples. But nothing is worse than examples that don't work because the code has changed since the documentation was written.\" - rustbook"},"headings":[{"depth":1,"headingId":"jest-markdown-pipeline","title":"Jest Markdown Pipeline","children":[{"depth":2,"headingId":"comments-parsing","title":"Comments Parsing","children":[{"depth":3,"headingId":"this-section-is-generated-by-the-code-snippet-below","title":"This section is generated by the code snippet below.","children":[]}]},{"depth":2,"headingId":"including-codeblocks","title":"Including Codeblocks","children":[]}]}],"html":"

Jest Markdown Pipeline

\n

\"Nothing is better than documentation with examples. But nothing is worse than examples that\ndon't work because the code has changed since the documentation was written.\" - rustbook

\n

Example code blocks in our markdown or inline documentation comments can be useful to quickly\ndemonstrate how one can use our software. As they are part of our living standards, each example\ncode should be functional code that can be asserted and tested. Documentation example code should be\nautomated, tested and linted as part of our workflow.

\n

Initially, we were thinking of creating a md-jest for parsing code blocks in markdown and transforming them into\njest tests. Similar to how ts-jest transform TS to CommonJS, but using contented-processor to transform MD files.

\n

@eli-lim suggested we transform jest files *.test.ts into Markdown instead. We\nget the DX of writing test with Jest and IDE support (without having to support write our own runner). It is much\neasier to transform comments to markdown than transform markdown to code (although not much harder, the focus here is\non the DX). Further, you get the natural flow of writing narrative and writing tests as a narrative.

\n
\n

This page, is written in a jest test file. JestMarkdown.spec.ts

\n
\n

Comments Parsing

\n

All comments are automatically picked up as Markdown with indent stripped. Indent are stripped using\nstrip-indent, * are also stripped. For bullet points, you should use - and avoid using * to prevent\nunintentional stripping.

\n\n
\n

This section is generated by the code snippet below.

\n

This is a multi line with * stripped from each line.

\n

This is a Line Comment

\n

This is a Block Comment

\n

This is a Multi Line\nBlock Comment without *.

\n
/**\n * ### This section is generated by the code snippet below.\n *\n * This is a multi line with `*` stripped from each line.\n */\n// This is a `Line Comment`\n/* This is a `Block Comment` */\n/* This is a `Multi Line`\n `Block Comment` without `*`. */
\n

Including Codeblocks

\n

JestMarkdown has the ability to \"pickup\" codes and add them into a codeblock. Codeblock is parsed line by line,\n@contented codeblock:start indicate the starting line and @contented codeblock:end indicate the ending line.\nEverything between will be included into a codeblock. Although not recommended, you can nest multiple\n@contented codeblock between.

\n
'@contented codeblock:start',
\n
'@contented codeblock:end',
\n
it('this it statement is in a codeblock with nested codeblock', () => {\n  const symbols = [\n    // @contented codeblock:start\n    '@contented codeblock:start',\n    // @contented codeblock:end\n    'everything in between will be included as a TypeScript codeblock ```ts\\n```',\n    // @contented codeblock:start\n    '@contented codeblock:end',\n    // @contented codeblock:end\n  ];\n  expect(join(...symbols)).toBeDefined();\n});
"}