elastic / elastic/docs-builder
Testing: Storybook like snapshot testing feature
- Dominant language
- C#
- Stars
- 24
- Forks
- 44
- Avg merge
- 1d 7h
- Merged PRs (30d)
- 146
Description
## Context
Currently, our documentation frequently uses a "tab set" pattern to display examples, separating "Output" from "Markdown" source. While effective for presentation, this approach doesn't inherently facilitate the testing of our Markdown rendering.
## Proposal: Introduce a "Markdown Example Testing" Component
I propose we develop a dedicated component that not only renders Markdown content for documentation but can also be leveraged as a robust **Markdown test runner**.
Imagine a system where:
* This new component takes Markdown content as input.
* It renders this Markdown, just as it would appear in our documentation.
* The rendered output is then compared against a **snapshot**.
* Crucially, this system would include the familiar capabilities of snapshot testing, such as the ability to easily **update snapshots** when changes to the Markdown rendering are intentional.
This component would effectively merge our documentation examples with our testing infrastructure.
## Why This Matters: Efficiency & Quality
Implementing this "Markdown Example Testing" component offers significant benefits:
* **📈 Increased Efficiency:** We would combine the efforts of documenting and testing Markdown syntax into a single, cohesive workflow. This eliminates redundant manual checks and ensures our examples are always accurate.
* **🛡️ Enhanced Test Coverage:** This approach would dramatically increase our test coverage for Markdown rendering, catching regressions and inconsistencies proactively.
* **💡 Improved Developer Experience:** Developers could write Markdown examples with the confidence that they are automatically tested, leading to a more streamlined and less error-prone documentation process.
This initiative represents a significant step towards a more robust, efficient, and reliable documentation and development workflow.
Contributor guide
Assessment
This issue has not been assessed yet.