A test framework for MkDocs projects
Project description
A testing framework (plugin + test fixture)
for MkDocs projects
Description
What problem does it solve?
Currently the quickest way for maintainers of
an MkDocs website project
(or developers of an MkDocs plugin)
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
The plugin exports thenav
object, in the form of a dictionary of Page objects.
Usage
Installation
From pypi
pip install mkdocs-test
Locally (Github)
pip install .
Or, to install the test dependencies (for testing this package, not MkDocs projects):
pip install .[test]
Installing the plugin
⚠️ The plugin is a pre-requisite
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
):
plugins:
- search
- ...
- test
Performing basic tests
The choice of testing tool is up to you (the examples in this package were tested with pytest).
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
# 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
page.markdown
contains the markdown after possible transformations by plugins; whereaspage.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.
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
print(project.config.site_name)
Accessing page metadata
page = project.get_page('index')
assert page.meta.foo = 'hello' # key-value pair in the page's frontmatter
Reading the log
# 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
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file mkdocs_test-0.5.3.tar.gz
.
File metadata
- Download URL: mkdocs_test-0.5.3.tar.gz
- Upload date:
- Size: 18.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.0.0 CPython/3.10.11
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2fd57bfadbc8eb10975e4984d52d82383d64916b0b2dbdb4e4c7a2e67f976688 |
|
MD5 | 15e6e11dcebb5bddc5cac96dd07197ca |
|
BLAKE2b-256 | 7482006694bfcddb5308b9db21195181e0d839a3b8d6372f7c09dc9151ab38ad |
File details
Details for the file mkdocs_test-0.5.3-py3-none-any.whl
.
File metadata
- Download URL: mkdocs_test-0.5.3-py3-none-any.whl
- Upload date:
- Size: 16.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.0.0 CPython/3.10.11
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | bf951f2c26cf2f94268a28c6189e13749db32ad5d2a06e36e492aaaf86341731 |
|
MD5 | 45a04d047559a3cb2bd43d59e6e93142 |
|
BLAKE2b-256 | d3a47d9763e5a280ff7f966c3c6c94fc22c71e35c90bfb3ca2dbc0ff301f50a6 |