[Feature]: test-based documentation with jest - experimental

[gabrielogregorio]

🚀 Feature Proposal

I would like to have the possibility for jest to generate a JSON documenting a feature/endpoint, similar to this project I'm doing

https://github.com/gabrielogregorio/docbytest.

And this practical example, a documentation of a simple API entirely based on tests. I had to do some workarounds that I wouldn't need if I had access to the jest core.

https://backend-valorant.herokuapp.com/docs

Motivation

Currently we have to write codes, write tests and write documentations.

Sometimes the documentation lies, they deceive and do not agree with reality.

The tests end up being the most reliable point of the application, and if the tests are done already thinking about a documentation by tests, we would have the best of several worlds.

Jest would almost completely eliminate the documentation step, and ensure that the documentation is always up to date and that would also encourage unit and integration testing.

My project was one of the most interesting things I've ever done, with few adaptations, my API had documentation that accompanies the tests.

I have already followed other teams and people using it, and this problem of the documentation being updated is very annoying, 3 points(dev, tests and docs) to worry about in development.

Example

The documentation would be done following the examples:

example in pratic (docbytest) https://github.com/gabrielogregorio/valorant-tips-api/blob/main/src/test/post.test.ts

// [doc] for public docs
// [dev] for dev docs
// etc
it("✅ [doc]: Register a user", () => {
  // docs:  Any comment

  // setup that jest/docs should ignore
  jest.setup(() => {
    //
  });

  // for jest control, or use supertest with jest....
  const myRequest = await jest.request.get('https://api.com.br/users');

/* partials would be a feature to expect values ​​that are not in our
  control, for example an ID, which can be random. It's simpler to do
  so than expecting exact values. (I suffered with this problem in docbytetest)
  */
  const idAleatory = jest.docs( { type: string, min: 10, max: 15, required: true, example: '96231924642626134'})

  // request.data is body for docs
  expect(myRequest.data).partials( { id: idAleatory }).toEqual([
    {
      id: idAleatory,
      name: 'greg'
    },
    {
      id: idAleatory,
      name: 'maria'
    },
  ])

  // request.statusCode is statusCode for docs
  expect(myRequest.statusCode).toEqual(200)
})

// and result in json docs. ( follow the openapi pattern?)

{
  "name": "✅ Register a user",
  "url": "https://api.com.br/users",
  "statusCode": 200, 
  "markdownComment": "Any comment",
  "response": [
    {
      "id": "96231924642626134",
      "name": "greg"
    },
    {
      "id": "96231924642626134",
      "name": "maria"
    }
  ] 
}

---

This feature can be expanded to document various other scenarios, such as helpers, components (in the case of reactjs for example), and many other things.

And as I said, the idea works, it's possible to generate documentation, at least from endpoints.

My docbytest project is fully experimental and proves the concept is possible, I think this should be in Jest

https://github.com/gabrielogregorio/docbytest

Pitch

This being at the core of jest, perhaps the biggest testing tool in the world, we would have access to several facilities, such as the partials feature that I need it for this idea to work fully.

We would also have a testing incentive, which would be available natively in millions of projects using jest

If the idea matures, we would eliminate an entire stage of software development, merging it with the testing stage.

We would have fully tested documentation.

This could be expanded by tools with the react testing library.

In the future, we could have business rule documentation, fully based on a real test in the application.

When a feature was removed/modified, a test would be affected, the test adjustment would mean a documentation adjustment.

The challenges in developing this documentation-by-test capability could set a milestone in modern software development.

[github-actions[bot]]

This issue is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 30 days.

[github-actions[bot]]

This issue was closed because it has been stalled for 30 days with no activity. Please open a new issue if the issue is still relevant, linking to this one.

[github-actions[bot]]

This issue was closed because it has been stalled for 30 days with no activity. Please open a new issue if the issue is still relevant, linking to this one.

[SimenB]

This is a cool idea @gabrielogregorio, sorry I missed it!

That said, I don't think this necessarily belongs in core. It sounds to me like a special case of a snapshot matcher? Have you tried building one?

[gabrielogregorio]

no problems @SimenB, I will study about this

the most I've developed so far is a regex based system, the script opens a test(.spec) file and extracts relevant information, I don't know if this is the best way, in my experience with the docbytest project it brought some complications, for example create a regex based system that understands typescript, that understands relative, absolute, path alias, which analyzes responses received during a test, etc. Things that jest I believe has already resolved.

Perhaps the documentation could be generated exactly like the test coverage system, after the test, the system would analyze everything that happened (and that is following a pattern to be documented), and generate a .json that would be the documentation.

This json, other libraries could use to display a web page for example.

And I could be wrong, but I believe that we could have a documentation system in tests with jest, which would increase the usefulness of testing in the eyes of the product teams, and encourage improvements in other libraries, in my opinion.

[github-actions[bot]]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs. Please note this issue tracker is not a help forum. We recommend using StackOverflow or our discord channel for questions.