{"id":15012812,"url":"https://github.com/lovasoa/docurun","last_synced_at":"2025-04-12T03:31:03.884Z","repository":{"id":251417863,"uuid":"837387566","full_name":"lovasoa/docurun","owner":"lovasoa","description":"Executable documentation, and self-documenting end-to-end tests.","archived":false,"fork":false,"pushed_at":"2024-08-17T11:07:16.000Z","size":2565,"stargazers_count":17,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-11T12:51:57.138Z","etag":null,"topics":["documentation","end-to-end-testing","playwright","static-site","testing"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lovasoa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-02T21:19:18.000Z","updated_at":"2024-11-12T13:20:05.000Z","dependencies_parsed_at":"2024-11-07T10:02:15.240Z","dependency_job_id":"b88418de-0a99-496c-9884-5559a7329bee","html_url":"https://github.com/lovasoa/docurun","commit_stats":{"total_commits":17,"total_committers":1,"mean_commits":17.0,"dds":0.0,"last_synced_commit":"1a8aa7dbfc2438bbde2bb2ea2290dc5e0949e063"},"previous_names":["lovasoa/docurun"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lovasoa%2Fdocurun","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lovasoa%2Fdocurun/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lovasoa%2Fdocurun/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lovasoa%2Fdocurun/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lovasoa","download_url":"https://codeload.github.com/lovasoa/docurun/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248512507,"owners_count":21116614,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","end-to-end-testing","playwright","static-site","testing"],"created_at":"2024-09-24T19:43:15.365Z","updated_at":"2025-04-12T03:31:01.999Z","avatar_url":"https://github.com/lovasoa.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DocuRun\n\n\u003ccenter\u003e \u003cimg src=\"https://github.com/user-attachments/assets/c1792d88-5705-4780-b8df-c7e17d6116ef\"\u003e \u003c/center\u003e\n\nDocuRun is a tool to run your documentation as integration tests.\n\n## Why ?\n\nI bet both your **integration tests** and your **documentation** are disappointing.\n\n - Your integration tests are probably hard to write, hard to read, and hard to debug.\n   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.\n - Your end user documentation is probably out of date, because the developers don't want to update it every time they change the code.\n   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.\n\nIf you make a change that breaks the documented behavior of the user interface, you probably only find out when your users complain.\n\n## What is DocuRun ?\n\nDocuRun is a tool that takes markdown files including [playwright](https://playwright.dev/) code blocks and runs them as integration tests.\nIt produces a beautiful documentation website with screenshots taken during the tests.\n\n## How to use DocuRun\n\n1. Write your documentation in markdown files, including code blocks that describe how to use your application.\n   Create a [`docurun/index.md`](./docurun/download_sqlpage.md) file that looks like this: ![sqlpage.md](screenshots/sqlpage-md.png)\n2. Run DocuRun on your markdown files\n    ```bash\n    npx docurun\n    ```\n3. Docurun will display a nice report on its standard output showing which markdown files ran successfully and which failed.\n   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.\n   It will also create a `docurun/website/` directory containing a static website with your documentation and screenshots.\n   If some tests failed, the documentation will contain the screenshots of the page at the time of the failure, and the error message.\n\n### Docker\n\nYou can also run DocuRun in a docker container, without having to install node.js on your machin:\n\n```bash\ndocker run -v $(pwd)/docurun:/docurun -it lovasoa/docurun\n```\n\nSee [lovaoa/docurun](https://hub.docker.com/r/lovasoa/docurun) on Docker Hub.\n\n## Screenshots\n\n### SQLPage\n\nThis shows the executable documentation of the [SQLPage](https://sql.ophir.dev/) website building tool.\n\n![sqlpage.md](screenshots/sqlpage-md.png)\n![sqlpage docs](screenshots/sqlpageRendered.png)\n\n### Github stars\n![gh_star_md](screenshots/starImage.png)\n![gh_star_render](screenshots/starRenderImage.png)\n\n### Errors\n\nAn error run looks like this in the terminal\n\n```\n$ npx docurun\n\n\u003e docurun@0.0.1 start\n\u003e node cli.js\n\nProcessing all files in ./docurun/:\n - download_sqlpage.md\n - star_a_repository.md.\nSaving results to ./docurun/website/.\n\n✅ download_sqlpage\nError while executing code:\nawait page.getByText('inexistent element').click()\n\nlocator.click: Timeout 30000ms exceeded.\nCall log:\n  - waiting for getByText('inexistent element')\n\n❌ star_a_repository\n```\n\nAnd rendered:\n\n![error](screenshots/error.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flovasoa%2Fdocurun","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flovasoa%2Fdocurun","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flovasoa%2Fdocurun/lists"}