Test code blocks in Markdown files.

This project contains the following:

- `test.sh`: The primary entrypoint for running tests.
  Copies Markdown files to a temporary directory shared with the `test` Docker image and runs the test container.
- `test/run-tests.sh`: The Docker image entrypoint.
  Substitutes placeholders with environment variables in code blocks.
  Passes test files to test runners (for example, `pytest --codeblocks` for Python and shell code samples).
- `compose.yaml` and `Dockerfile`: Docker image for the **test** service that installs test dependencies and passes test files to test runners.

## Set configuration values

To set your InfluxDB credentials for testing, create a `.env.<product-name>` file and add key=value properties--for example, in `.env.serverless`

```text
INFLUX_HOST=https://us-east-1-1.aws.cloud2.influxdata.com
INFLUX_HOSTNAME=us-east-1-1.aws.cloud2.influxdata.com
INFLUX_TOKEN=5Vz...
INFLUX_ORG=28d...
INFLUX_DATABASE=jason-test-create-bucket
INFLUX_RETENTION_POLICY=test-autogen
```

Storing configuration properties in a  `.env` (dotenv) file is generally preferable to using environment variables.

## Build the image

1.  Install Docker for your system.

2.  Build the Docker image.

    ```shell
    docker compose build test
    ```

    After editing configuration or files used by the image, re-run the preceding build command.

## Run tests

Test code blocks in Markdown files that have changed relative to your git `master` branch:

```sh
sh test.sh
```

Test code blocks in files that match a pattern:

```sh
sh test.sh ./content/**/*.md
```

`test.sh` copies files into `./test/tmp/` for testing and runs the tests in Docker.

### Test runners

_Experimental--work in progress_

[pytest-codeblocks](https://github.com/nschloe/pytest-codeblocks/tree/main) extracts code from python and shell Markdown code blocks and executes assertions for the code.
If you don't assert a value, `--codeblocks` considers a non-zero exit code to be a failure.
_Note_: `pytest --codeblocks` uses Python's `subprocess.run()` to execute shell code.

To assert (and display) the expected output of your code, follow the code block with the `<!--pytest-codeblocks:expected-output-->` comment tag, and then the expected output in a code block--for example:

<!-- Your Markdown content -->

```python
print("Hello, world!")
```

<!--pytest-codeblocks:expected-output-->

If successful, the output is the following:

```
Hello, world!
```

<!-- End Markdown content -->

pytest-codeblocks has features for skipping tests and marking blocks as failed.
To learn more, see the pytest-codeblocks README and tests.

#### Other tools and ideas for testing code blocks

The `codedown` NPM package extracts code from Markdown code blocks for each language and
can pipe the output to a test runner for the language.

`pytest` and `pytest-codeblocks` use the Python `Assertions` module to keep testing overhead low.
Node.js also provides an `Assertions` package.

The `runmd` NPM package runs `javascript` code blocks in Markdown and generates a new Markdown file with the code block output inserted.

## Troubleshoot

### Pytest collected 0 items

Potential reasons:

- See the test discovery options in `pytest.ini`.
- For Python code blocks, use the following delimiter:

    ```python
    # Codeblocks runs this block.
    ```

  `pytest --codeblocks` ignores code blocks that use the following:

    ```py
    # Codeblocks ignores this block.
    ```