| Name | mkdocs-test JSON |
| Version |
0.5.1
JSON |
| download |
| home_page | None |
| Summary | A test framework for MkDocs projects |
| upload_time | 2024-10-10 07:29:50 |
| maintainer | None |
| docs_url | None |
| author | Laurent Franceschetti |
| requires_python | None |
| license | LICENSE |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<div align="center">
# A testing framework (plugin + test fixture)<br>for MkDocs projects
</div>
<!-- To update, run the following command:
markdown-toc -i README.md
-->
<!-- toc -->
- [A testing framework (plugin + test fixture)for MkDocs projects](#a-testing-framework-plugin--test-fixturefor-mkdocs-projects)
- [Description](#description)
- [What problem does it solve?](#what-problem-does-it-solve)
- [MkDocs-Test](#mkdocs-test)
- [Usage](#usage)
- [Installation](#installation)
- [From pypi](#from-pypi)
- [Locally (Github)](#locally-github)
- [Installing the plugin](#installing-the-plugin)
- [Performing basic tests](#performing-basic-tests)
- [Tests on a page](#tests-on-a-page)
- [Performing advanced tests](#performing-advanced-tests)
- [Reading the configuration file](#reading-the-configuration-file)
- [Accessing page metadata](#accessing-page-metadata)
- [Reading the log](#reading-the-log)
- [License](#license)
<!-- tocstop -->
## Description
### What problem does it solve?
Currently the quickest way for maintainers of
an [MkDocs](https://www.mkdocs.org/) website project
(or developers of an [MkDocs plugin](https://www.mkdocs.org/dev-guide/plugins/))
to check whether an MkDocs project builds correctly,
is to run `mkdocs build` (possibly with the `--strict` option).
It leaves the following issues open:
- This is a binary proposition: it worked or it didn't.
- It doesn't perform integrity tests on the pages; if something started to
go wrong, the issue might emerge only later.
- If something went already wrong, it doesn't necessarily say where, or why.
One solution is to write an ad-hoc program to make tests on
the target (HTML) pages; this requires
knowing in advance where those files will be stored.
Manually keeping track of those target files is doable
for small documentation projects;
but for larger ones, or for conducting systematic tests, it becomes
quickly impractical.
### MkDocs-Test
The purpose of Mkdocs-Test is to facilitate the comparison of source pages
(Markdown files) and destination pages (HTML) in an MkDocs project.
MkDocs-Test is a framework composed of two parts:
- an MkDocs plugin (`test`): it creates a `__test__` directory,
which contains the data necessary to map the pages of the website.
- a framework for conducting the test. The `DocProject`
class groups together all the information necessary for the tests on a
specific MkDocs project.
> 📝 **Technical Note** <br> The plugin exports the `nav` object,
> in the form of a dictionary of Page objects.
## Usage
### Installation
#### From pypi
```sh
pip install mkdocs-test
```
#### Locally (Github)
```sh
pip install .
```
Or, to install the test dependencies (for testing _this_ package,
not MkDocs projects):
```sh
pip install .[test]
```
### Installing the plugin
> ⚠️ **The plugin is a pre-requisite** <br> The framework will not work
> without the plugin (it exports the pages map into the
> `__test__` directory).
Declare the `test` plugin in your config file (typically `mkdocs.yml`):
```yaml
plugins:
- search
- ...
- test
```
### Performing basic tests
The choice of testing tool is up to you (the examples in this package
were tested with
[pytest](https://docs.pytest.org/en/stable/)).
```python
from mkdocs_test import DocProject
project = DocProject() # declare the project
# (by default, the directory where the program resides)
project.build(strict=False, verbose=False)
# build the project; these are the default values for arguments
assert project.success # return code of the build is zero (success) ?
print(project.build_result.returncode) # return code from the build
# perform automatic integrity checks (do pages exist?)
project.self_check()
```
### Tests on a page
Each page of the MkDocs project can be tested separately
```python
# find the page by relative pathname:
page = project.pages['index.md']
# find the page by name, filename or relative pathname:
page = project.get_page('index')
# easy, and naïve search on the target html page
assert "hello world" in page.html
# find the words "second page", under the header that contains "subtitle"
# at level 2; arguments header and header_level are optional
# the method returns the text so found (if found)
# the search is case insensitive
assert page.find('second page', header="subtitle", header_level=2)
```
> ⚠️ **Two markdown versions** <br> `page.markdown`
> contains the markdown after possible transformations
> by plugins; whereas `page.source.markdown` contains the exact
> markdown in the file.
>
> If you wish to have the complete source file (including the frontmatter),
> use `page.source.text`.
## Performing advanced tests
### Reading the configuration file
```python
print(project.config.site_name)
```
### Accessing page metadata
```python
page = project.get_page('index')
assert page.meta.foo = 'hello' # key-value pair in the page's frontmatter
```
### Reading the log
```python
# search in the trace (naïve)
assert "Cleaning site" in project.trace
# get all WARNING log entries
entries = myproject.find_entries(severity='WARNING')
# get the entry from source 'test', containing 'debug file' (case-insensitive)
entry = project.find_entry('debug file', source='test')
assert entry, "Entry not found"
```
## License
MIT License
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocs-test",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Laurent Franceschetti",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/a3/71/1775ca36b5f08c83a23e3e55f66d8b9a391b57030f6bdda5b070c008db81/mkdocs_test-0.5.1.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n\n\n# A testing framework (plugin + test fixture)<br>for MkDocs projects\n\n</div>\n\n<!-- To update, run the following command:\nmarkdown-toc -i README.md \n-->\n\n<!-- toc -->\n\n- [A testing framework (plugin + test fixture)for MkDocs projects](#a-testing-framework-plugin--test-fixturefor-mkdocs-projects)\n - [Description](#description)\n - [What problem does it solve?](#what-problem-does-it-solve)\n - [MkDocs-Test](#mkdocs-test)\n - [Usage](#usage)\n - [Installation](#installation)\n - [From pypi](#from-pypi)\n - [Locally (Github)](#locally-github)\n - [Installing the plugin](#installing-the-plugin)\n - [Performing basic tests](#performing-basic-tests)\n - [Tests on a page](#tests-on-a-page)\n - [Performing advanced tests](#performing-advanced-tests)\n - [Reading the configuration file](#reading-the-configuration-file)\n - [Accessing page metadata](#accessing-page-metadata)\n - [Reading the log](#reading-the-log)\n - [License](#license)\n\n<!-- tocstop -->\n\n## Description\n\n### What problem does it solve?\n\nCurrently the quickest way for maintainers of \nan [MkDocs](https://www.mkdocs.org/) website project\n(or developers of an [MkDocs plugin](https://www.mkdocs.org/dev-guide/plugins/)) \nto check whether an MkDocs project builds correctly, \nis to run `mkdocs build` (possibly with the `--strict` option).\n\nIt leaves the following issues open:\n- This is a binary proposition: it worked or it didn't.\n- It doesn't perform integrity tests on the pages; if something started to\n go wrong, the issue might emerge only later.\n- If something went already wrong, it doesn't necessarily say where, or why.\n\nOne solution is to write an ad-hoc program to make tests on\nthe target (HTML) pages; this requires\nknowing in advance where those files will be stored.\n\nManually keeping track of those target files is doable\nfor small documentation projects;\nbut for larger ones, or for conducting systematic tests, it becomes\nquickly impractical.\n\n\n\n### MkDocs-Test\nThe purpose of Mkdocs-Test is to facilitate the comparison of source pages\n(Markdown files) and destination pages (HTML) in an MkDocs project.\n\nMkDocs-Test is a framework composed of two parts:\n\n- an MkDocs plugin (`test`): it creates a `__test__` directory, \n which contains the data necessary to map the pages of the website.\n\n- a framework for conducting the test. The `DocProject`\n class groups together all the information necessary for the tests on a\n specific MkDocs project. \n\n\n> \ud83d\udcdd **Technical Note** <br> The plugin exports the `nav` object,\n> in the form of a dictionary of Page objects.\n\n## Usage\n\n### Installation \n\n#### From pypi\n\n```sh\npip install mkdocs-test\n```\n\n#### Locally (Github)\n\n```sh\npip install .\n```\n\nOr, to install the test dependencies (for testing _this_ package,\nnot MkDocs projects):\n\n```sh\npip install .[test]\n```\n\n### Installing the plugin\n\n> \u26a0\ufe0f **The plugin is a pre-requisite** <br> The framework will not work\n> without the plugin (it exports the pages map into the\n> `__test__` directory).\n\nDeclare the `test` plugin in your config file (typically `mkdocs.yml`):\n\n```yaml\nplugins:\n - search\n - ...\n - test\n```\n\n### Performing basic tests\n\nThe choice of testing tool is up to you (the examples in this package \nwere tested with\n[pytest](https://docs.pytest.org/en/stable/)).\n\n```python\nfrom mkdocs_test import DocProject\n\nproject = DocProject() # declare the project\n # (by default, the directory where the program resides)\nproject.build(strict=False, verbose=False)\n # build the project; these are the default values for arguments\n\nassert project.success # return code of the build is zero (success) ?\nprint(project.build_result.returncode) # return code from the build\n\n# perform automatic integrity checks (do pages exist?)\nproject.self_check()\n\n```\n### Tests on a page\n\nEach page of the MkDocs project can be tested separately\n\n```python\n# find the page by relative pathname:\npage = project.pages['index.md']\n\n# find the page by name, filename or relative pathname:\npage = project.get_page('index')\n\n# easy, and na\u00efve search on the target html page\nassert \"hello world\" in page.html\n\n# find the words \"second page\", under the header that contains \"subtitle\"\n# at level 2; arguments header and header_level are optional\n# the method returns the text so found (if found)\n# the search is case insensitive\nassert page.find('second page', header=\"subtitle\", header_level=2)\n```\n\n> \u26a0\ufe0f **Two markdown versions** <br> `page.markdown`\n> contains the markdown after possible transformations\n> by plugins; whereas `page.source.markdown` contains the exact\n> markdown in the file.\n>\n> If you wish to have the complete source file (including the frontmatter), \n> use `page.source.text`.\n\n\n\n## Performing advanced tests\n\n### Reading the configuration file\n\n```python\nprint(project.config.site_name)\n\n\n```\n\n### Accessing page metadata\n\n```python\npage = project.get_page('index')\nassert page.meta.foo = 'hello' # key-value pair in the page's frontmatter\n```\n\n### Reading the log\n\n```python\n# search in the trace (na\u00efve)\nassert \"Cleaning site\" in project.trace\n\n# get all WARNING log entries\nentries = myproject.find_entries(severity='WARNING')\n\n# get the entry from source 'test', containing 'debug file' (case-insensitive)\nentry = project.find_entry('debug file', source='test')\nassert entry, \"Entry not found\"\n```\n\n## License\n\nMIT License\n",
"bugtrack_url": null,
"license": "LICENSE",
"summary": "A test framework for MkDocs projects",
"version": "0.5.1",
"project_urls": {
"Source": "https://github.com/fralau/mkdocs-test"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "522044d1be884e5abd3a488cd86d6b286d86c52a2b61e9b38a94c48b8629add7",
"md5": "d39b1f687761cd8f0093099504e5f8f7",
"sha256": "ebfaba9f7d94c768ba9d20871efb150b56d86ff04c1c428b936b9aeb7fe44cea"
},
"downloads": -1,
"filename": "mkdocs_test-0.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d39b1f687761cd8f0093099504e5f8f7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 15217,
"upload_time": "2024-10-10T07:29:49",
"upload_time_iso_8601": "2024-10-10T07:29:49.726847Z",
"url": "https://files.pythonhosted.org/packages/52/20/44d1be884e5abd3a488cd86d6b286d86c52a2b61e9b38a94c48b8629add7/mkdocs_test-0.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a3711775ca36b5f08c83a23e3e55f66d8b9a391b57030f6bdda5b070c008db81",
"md5": "a02bd67edfd5a2a5db576837902f2b1a",
"sha256": "dd197d9c0c2cdcff77c5ff6726d959d3ad45f594da5b117dfe4413a41cd6caf9"
},
"downloads": -1,
"filename": "mkdocs_test-0.5.1.tar.gz",
"has_sig": false,
"md5_digest": "a02bd67edfd5a2a5db576837902f2b1a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 17476,
"upload_time": "2024-10-10T07:29:50",
"upload_time_iso_8601": "2024-10-10T07:29:50.754551Z",
"url": "https://files.pythonhosted.org/packages/a3/71/1775ca36b5f08c83a23e3e55f66d8b9a391b57030f6bdda5b070c008db81/mkdocs_test-0.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-10 07:29:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fralau",
"github_project": "mkdocs-test",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mkdocs-test"
}
