| Name | mkdocs-test JSON |
| Version |
0.5.6
JSON |
| download |
| home_page | None |
| Summary | A test framework for MkDocs projects |
| upload_time | 2025-08-11 16:31:26 |
| 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
[](https://opensource.org/licenses/MIT)
[View the documentation](https://mkdocs-test-plugin.readthedocs.io/en/latest/) on Read the Docs
</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)
- [Testing the HTML](#testing-the-html)
- [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?
Traditionally, the quickest way for maintainers of
an existing [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.
### 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_text_text('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`.
### Testing the HTML
You can directly access the `.find()` and `.find_all()` methods
offered by [BeautifulSoup](https://www.crummy.com/software/BeautifulSoup/bs4/doc/#find-all).
```python
page = project.get_page('foo')
headers = page.find_all('h2') # get all headers of level 2
for header in headers:
print(header.string)
script = page.find('script', type="module")
assert 'import foo' in script.string
```
## 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/b4/fc/82667c82079719c475ef6c6e30b3544941e4e6990fe7259869acf815ad58/mkdocs_test-0.5.6.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n\n\n# A testing framework (plugin + test fixture)<br>for MkDocs projects\n\n\n[](https://opensource.org/licenses/MIT) \n\n\n\n \n\n[View the documentation](https://mkdocs-test-plugin.readthedocs.io/en/latest/) on Read the Docs\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 - [Testing the HTML](#testing-the-html)\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\nTraditionally, the quickest way for maintainers of \nan existing [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\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_text_text('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### Testing the HTML\nYou can directly access the `.find()` and `.find_all()` methods \noffered by [BeautifulSoup](https://www.crummy.com/software/BeautifulSoup/bs4/doc/#find-all). \n\n```python\npage = project.get_page('foo')\nheaders = page.find_all('h2') # get all headers of level 2\nfor header in headers:\n print(header.string)\n\nscript = page.find('script', type=\"module\")\nassert 'import foo' in script.string\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.6",
"project_urls": {
"Source": "https://github.com/fralau/mkdocs-test"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5845a80684fe274f6da82ba73f409eaf4b2a3857a893489d083586c66cb95b40",
"md5": "9d800281becedfc0510adc2e8122de46",
"sha256": "5c869533ee0b70b04bba49b4ee71e1633929ae0ccee913fd962f12cf32f09bde"
},
"downloads": -1,
"filename": "mkdocs_test-0.5.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9d800281becedfc0510adc2e8122de46",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 27072,
"upload_time": "2025-08-11T16:31:23",
"upload_time_iso_8601": "2025-08-11T16:31:23.707828Z",
"url": "https://files.pythonhosted.org/packages/58/45/a80684fe274f6da82ba73f409eaf4b2a3857a893489d083586c66cb95b40/mkdocs_test-0.5.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b4fc82667c82079719c475ef6c6e30b3544941e4e6990fe7259869acf815ad58",
"md5": "79c3a82205b24312b1c1fe708463fa0c",
"sha256": "4250f8c2372d51ef32376957815c73ddecd8d81de4483d592e4c8450d8ade75d"
},
"downloads": -1,
"filename": "mkdocs_test-0.5.6.tar.gz",
"has_sig": false,
"md5_digest": "79c3a82205b24312b1c1fe708463fa0c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 24722,
"upload_time": "2025-08-11T16:31:26",
"upload_time_iso_8601": "2025-08-11T16:31:26.037798Z",
"url": "https://files.pythonhosted.org/packages/b4/fc/82667c82079719c475ef6c6e30b3544941e4e6990fe7259869acf815ad58/mkdocs_test-0.5.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-11 16:31:26",
"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"
}
