Skip to main content

A test framework for MkDocs projects

Project description

MkDocs-Test

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 the nav 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; 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.

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

mkdocs_test-0.5.3.tar.gz (18.4 kB view details)

Uploaded Source

Built Distribution

mkdocs_test-0.5.3-py3-none-any.whl (16.0 kB view details)

Uploaded Python 3

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

Hashes for mkdocs_test-0.5.3.tar.gz
Algorithm Hash digest
SHA256 2fd57bfadbc8eb10975e4984d52d82383d64916b0b2dbdb4e4c7a2e67f976688
MD5 15e6e11dcebb5bddc5cac96dd07197ca
BLAKE2b-256 7482006694bfcddb5308b9db21195181e0d839a3b8d6372f7c09dc9151ab38ad

See more details on using hashes here.

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

Hashes for mkdocs_test-0.5.3-py3-none-any.whl
Algorithm Hash digest
SHA256 bf951f2c26cf2f94268a28c6189e13749db32ad5d2a06e36e492aaaf86341731
MD5 45a04d047559a3cb2bd43d59e6e93142
BLAKE2b-256 d3a47d9763e5a280ff7f966c3c6c94fc22c71e35c90bfb3ca2dbc0ff301f50a6

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page