TestFlows - Texts
Project description
TestFlows-Texts
TestFlows.com Open-Source Software Testing Framework Texts
Use testflows.texts
Python module to help you write auto verified software documentation
by combining your text with the verification procedure of the described functionality
in the same source file while leveraging the power and flexibility of TestFlows.com Open-Source Test Framework.
Source files for auto verified documentation by convention have .tfd
extension
and are written using Markdown. Therefore, all .tfd
files are valid
Markdown files. However, .tfd
files are only the source files for your documentation
that must be executed using tfs document run
command to produce final
Markdown documentation files.
$ tfs document run --input my_document.tfd --output my_document.md
Requirements
- Python3 >= 3.8
Install
You can install testflows.texts
using pip3
command:
pip3 install --upgrade testflows.texts
After installing testflows.texts
you will also have tfs
command available in your environment.
Writing Auto Verified Docs
Follow the example Markdown document to get to know how you can write auto verified docs yourself.
## This is a heading
This file is written using Markdown where you can have any number
of `python:testflows` code blocks that contain executable Python code.
```python:testflows
# This is Python code that will be executed when .tfd document is run.
msg = "Hello TestFlows Texts"
```
The scope is shared between all the code blocks in the same document.
```python:testflows
# so `msg` variable define above can also be accessed in this
# `python:testflows` code block
new_msg = msg + " Thanks for making verifying docs so easy!"
```
The output of executing `.tfd` document using `tfs document run`
is the final `.md` file with all the `python:testflows` code blocks
removed and replaced with the text added to the document using
the `text()` function.
```python:testflows
# Let's use `text()` function to add some text to our document
# dynamically in our Python code
text("add this line to the final Markdown document")
```
Any text outside the `python:testflows` code blocks are treated as Python
f-strings. This allows you to specify expressions for substitutions.
See [Python formatted string literals](https://docs.python.org/3/tutorial/inputoutput.html#formatted-string-literals)
for more details.
Here is an example where we will substitute the value of `msg` variable next {msg}.
But with Python f-strings you can specify even complex expressions. For example, we can
convert our string in `msg` to title case as follows {msg.title()}.
You can double your curly braces to escape them when substitution expression is not needed
using `{{` or `}}`.
By the way, your document can't contain any triple double quotes `"""`. If you need them then you have to
add them inside the `python:testflows` code block using `text()` function. For example,
```python:testflows
text('"""')
```
Well, this is pretty much it. With `testflows.texts` you have full power of full featured
test framework and Python language at your disposal to make sure your documentation always
stays to date.
Using tfs document run
$ tfs document run -h
usage: tfs document run [-h] [-i path [path ...]] [-o [path]] [-f]
---- o o o ----
| o o |
| 1 o 10010 o 0 |
| o o | TestFlows.com Open-Source Software Testing Framework v1.7.211208.1222904
--- o o oxx --
/ xx \
/ ^^^ xx \
------------------
Run executable document.
Executable documents are Markdown documents that
contain `python:testflows` code blocks which may contain
any Python code that will be run during document execution.
All text within executable document except for the
`python:testflows` code blocks are treated as Python f-strings.
Therefore, you must escape any `{`, `}` characters by doubling
them, for example: `{{` or `}}`, otherwise they will be treated
as f-string expressions.
Text must not contain triple quotes `"""`. If you need them
then you must use `text()` function within `python:testflows` code block
to explicitly add them to the the text.
For example:
```python:testflows
text('adding triple quotes """ to text')
```
Specify '--' at the end of the command line options to pass
options to the executable document writer program itself.
For example:
tfs document run -i <path>--o <path> -- --help
You must set PYTHONPATH when modules needed by the executable
document are not in the default path.
For example:
PYTHONPATH=<path/to/module> tfs document run -i <path> -o <path>
The `--input` can take multiple files and in such case if `--output`
is specified it is treated as directory name.
For example,
tfs document run -i `find $(pwd) -name "*.tfd"` -o . -f
or
tfs document run -i `find $(pwd) -name "*.tfd"` -o /path/to/output/dir -f
If input is '-' (stdin) and output is '.' then output file is 'document.md'
which is created in the current working directory.
optional arguments:
-h, --help show this help message and exit
-i path [path ...], --input path [path ...] input file, use '-' for stdin, default: stdin
-o [path], --output [path] output file or directory if multiple input files are
passed, default: '.' or if input is stdin then '-'.
The '.' means to create output file in the same
directory as the input file having .md extension and
the '-' means output to stdout.
-f, --force force to override existing output file if it already
exists
TestFlows.com Open-Source Software Testing Framework. Copyright 2021 Katteli Inc.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Hashes for testflows.texts-2.0.211209.1173148.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 454951f7c4cf2df97dec2a568eb756072104b78de03736005372d78d3496302f |
|
MD5 | 20485224adc5416e3ac15c65a43997fc |
|
BLAKE2b-256 | 13c9a071691e40a4a506396a3dd85990d1284bc654d7ad0b5d51181a971c7efc |