Generate document from end-to-end tests

In recent years, Domain-Driven Design (DDD) has become mainstream, making it easier to implement unit tests for methods in each layer.

However, implementing end-to-end (E2E) tests can be quite labor-intensive. To achieve a return on the effort invested, I am developing go-spectest/spectest.

The spectest libarary/cli (command line interface) generate E2E test results as documents in Markdown format.

Simple usecase for generating E2E test results

1. You implement unit tests for your API endpoints with spectest.
2. You run the E2E tests.
3. The spectest generate Markdown documents with the test results.
4. When you execute $ spectest index, spectest generates an index markdown for a directory full of markdown file.

Test code example

For example, let's consider an API that returns the health check of a server (GET /v1/health). The code to test the status code and body of this API is as follows:

func TestHealthCheck(t *testing.T) {
    spectest.New().
        Report(spectest.SequenceReport(spectest.ReportFormatterConfig{
            Path: filepath.Join("docs", "health"),
            Kind: spectest.ReportKindMarkdown,
        })).
        CustomReportName("health_success").
        Handler(api).
        Get("/v1/health").
        Expect(t).
        Body(`{"name": "naraku", "revision": "revision-0.0.1", "version":"v0.0.1"}`).
        Status(http.StatusOK).
        End()
}

In spectest.SequenceReport, you specify the "output destination for E2E test results" and indicate that the results should be output in Markdown format. With CustomReportName, you specify the filename for the Markdown file. The above code will generate a Markdown file named "docs/health/health_success.md".

E2E test result document example

The spectest also supports cases where API responses are not in JSON format. "Additionally, it can generate documentation in HTML format, not just markdown. For example, if the response body includes an image, it generates documentation in HTML format like the following:

Document index markdown file example

When you write a lot of E2E tests, the spectest generate multiple Markdown files.

It can become challenging for you to reference all these Markdown files individually. Therefore, you can use the spectest CLI to generate an index file with links to the Markdown files.

You execute the following command to generate an document index markdown file:

$ spectest index docs --title "naraku api result" 

Roadmap

Roadmap is here.

Goal

1. Generate Markdown documents from E2E test results to reduce the time developers spend on document creation.
2. Support BDD-style testing methods.
3. Become a versatile library that allows easy writing of unit tests for entities other than APIs.
4. Provide CLI commands to enhance the developer experience during unit test execution.

Related project

The spectest dynamically generates markdown without using text/template, however instead utilizes its own Markdown Builder (go-spectest/markdown) during the markdown generation.

This approach makes the code more readable and intuitive compared to using templates.