elastic / elastic/docs-builder

Testing: Storybook like snapshot testing feature

Open
#1,415 2 comments 0 reactions 0 assignees View on GitHub
ai-triaged ai:eng-question
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.