https://github.com/lovasoa/docurun
Executable documentation, and self-documenting end-to-end tests.
https://github.com/lovasoa/docurun
documentation end-to-end-testing playwright static-site testing
Last synced: 14 days ago
JSON representation
Executable documentation, and self-documenting end-to-end tests.
- Host: GitHub
- URL: https://github.com/lovasoa/docurun
- Owner: lovasoa
- Created: 2024-08-02T21:19:18.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2024-08-17T11:07:16.000Z (8 months ago)
- Last Synced: 2025-04-11T12:51:57.138Z (14 days ago)
- Topics: documentation, end-to-end-testing, playwright, static-site, testing
- Language: JavaScript
- Homepage:
- Size: 2.45 MB
- Stars: 17
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# DocuRun
DocuRun is a tool to run your documentation as integration tests.
## Why ?
I bet both your **integration tests** and your **documentation** are disappointing.
- Your integration tests are probably hard to write, hard to read, and hard to debug.
When something goes wrong, you have to dig through the code and try to guess at which point they differ from what you are doing manually in your browser.
- Your end user documentation is probably out of date, because the developers don't want to update it every time they change the code.
When you change the wording of a button, you have to remember to go update the screenshots in the documentation, and you probably won't.
If you make a change that breaks the documented behavior of the user interface, you probably only find out when your users complain.
## What is DocuRun ?
DocuRun is a tool that takes markdown files including [playwright](https://playwright.dev/) code blocks and runs them as integration tests.
It produces a beautiful documentation website with screenshots taken during the tests.
## How to use DocuRun
1. Write your documentation in markdown files, including code blocks that describe how to use your application.
Create a [`docurun/index.md`](./docurun/download_sqlpage.md) file that looks like this: 
2. Run DocuRun on your markdown files
```bash
npx docurun
```
3. Docurun will display a nice report on its standard output showing which markdown files ran successfully and which failed.
The exit code will be 0 if all tests passed, and 1 if some tests failed, which makes it easy to integrate in your CI/CD pipeline.
It will also create a `docurun/website/` directory containing a static website with your documentation and screenshots.
If some tests failed, the documentation will contain the screenshots of the page at the time of the failure, and the error message.
### Docker
You can also run DocuRun in a docker container, without having to install node.js on your machin:
```bash
docker run -v $(pwd)/docurun:/docurun -it lovasoa/docurun
```
See [lovaoa/docurun](https://hub.docker.com/r/lovasoa/docurun) on Docker Hub.
## Screenshots
### SQLPage
This shows the executable documentation of the [SQLPage](https://sql.ophir.dev/) website building tool.
### Github stars
### Errors
An error run looks like this in the terminal
```
$ npx docurun
> [email protected] start
> node cli.js
Processing all files in ./docurun/:
- download_sqlpage.md
- star_a_repository.md.
Saving results to ./docurun/website/.
✅ download_sqlpage
Error while executing code:
await page.getByText('inexistent element').click()
locator.click: Timeout 30000ms exceeded.
Call log:
- waiting for getByText('inexistent element')
❌ star_a_repository
```
And rendered:
