https://github.com/tokusumi/readme-code-testing
Helping test "any" code in readme with GitHub Action. All you need is unit testing synchronized external files in the ordinary way.
https://github.com/tokusumi/readme-code-testing
github-action readme-quality testing-practices
Last synced: about 2 months ago
JSON representation
Helping test "any" code in readme with GitHub Action. All you need is unit testing synchronized external files in the ordinary way.
- Host: GitHub
- URL: https://github.com/tokusumi/readme-code-testing
- Owner: tokusumi
- License: mit
- Created: 2020-11-17T10:16:05.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2023-11-27T19:47:16.000Z (over 1 year ago)
- Last Synced: 2025-02-23T10:24:59.358Z (about 2 months ago)
- Topics: github-action, readme-quality, testing-practices
- Language: Python
- Homepage:
- Size: 21.5 KB
- Stars: 13
- Watchers: 1
- Forks: 64
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- jimsghstars - tokusumi/readme-code-testing - Helping test "any" code in readme with GitHub Action. All you need is unit testing synchronized external files in the ordinary way. (Python)
README
# Readme code testing example
This repo demonstrates [Markdown Embed Code From File](https://github.com/marketplace/actions/markdown-embed-code-from-file) (GitHub Action).
This would helps testing for your code within readme (actually for markdown).
You could put code in external file and test them, as same as ordinary testing your code. You don't need copy & paste code and feel anxisous about compatibility anymore.
## Mark your code for embedding
This action could inspect your code, if you add a file path in code block as "\`\`\`lang:external/file/path.py\`\`\`".
The following code block has a file path `src/helloworld.py`:
```python:src/helloworld.py
def hello():
return "v1.0.0 world"
```
See [src/helloworld.py](./src/helloworld.py) as:
* Synchronized code.
* Highlighting code in readme.
* Not affected code rendering.
And notice that there are nothing to do re-embedding new/modified code. This action overrides code automatically if you change code in external file and commit it.
### Try it
Let's try demonstration in your repository as follows:
1. fork this repository.
1. edit [src/helloworld.py](./src/helloworld.py), create a new branch and start a pull request.
1. go to PR to check action result.
1. you can see auto updated readme at new branch you created above. (see if [above code block](#mark-your-code-for-embedding) is modified)
1. you can try again, if you edit it and commit again.
## More features
### Embedding specific lines
You might add specific lines from one file (ex. [src/mul.py](./src/mul.py)).
This action supports this with the syntax as "\`\`\`lang:external/file/path.py [start:end]\`\`\`" for it:
```py:src/mul.py [3-4]
def multiple(x):
return pow(x, 2)
```
### Multiple use
You might add one file path (ex. [src/mul.py](./src/mul.py)) for multiple code blocks:
```py:src/mul.py
from math import pow
def multiple(x):
return pow(x, 2)
```
It works!:
```py:src/mul.py
from math import pow
def multiple(x):
return pow(x, 2)
```
However, the other is not available.
### Non-existent file
Notice that this action goes to "fail" if a file you add does not exist.
## Multilingual
This action could work for any programming "language".
Ideally you could write as "\`\`\`lang:external/file/path.py\`\`\`", but actually this action does not inspect "lang", just read path and copy&paste strings into target code block in markdown.
So, missing "lang" is available:
```:src/helloworld.sh
#!/bin/bash
echo "hello"
```
## Formatting
Notice that this action uses markdown parser/formatter, so, if you don't update any code, readme may be updated if formatter works.