API Reference for MkDocs Test

Introduction

This page describes components of the MkDocs-Test API used by testing components.

A single MkDocs project contains a number of pages. Each page is a composite of the Markdown version, the metadata, and the fully formed HTML page that will be displayed on a browser.

Class: DocProject

Bases: object

An object that describes the current MkDocs project being tested (any plugin).

build_result property

Result of the build (low level)

config property

Get the configuration from the config file. All main items of the config are accessible with the dot notation. (config.site_name, config.theme, etc.)

If no config file available, provisionally returns an empty SuperDict.

config_file property

The config file

docs_dir property

The source directory of markdown files (full path). It attempts to get it from the config file (or returns the default 'docs' directory)

log property

The parsed trace (LogEntry objects)

log_severities property

List of severities (DEBUG, INFO, WARNING) found in the log

page_map_file property

The page map file exported by the Test plugin

pages property

The dictionary containing the pages (Markdown + HTML + ...) produced by the build.

project_dir property

The source directory of the MkDocs project (abs or relative path)

source_pages property

Get all documentation file names from self.docs_dir.

Returns:

A list of relative file paths (to self.docs_dir) for all files.

success property

Was the execution of the build a success?

test_dir property

The test directory (full path)

trace property

Trace of the execution (the log) as text

__init__(project_dir='', path='', new=False)

Initialize the documentation project.

Designed for pytest: if the path is not defined, it will take the path of the calling program.

Parameters:

Name Type Description Default
project_dir str

the project subdirectory name; default: empty, same level as path (the calling program)

 ''
path str

the path to the reference directory default: empty, i.e. directory of the calling program

 ''
new bool

create the project dir if it does not exist. (without clearing it) If you use the make_config() method, the docs_dir MUST be 'docs'.

 False
Note

It does not perform any build. The build() method must be called explicitly.

add_source_page(pathname, content, meta={})

Add a source page to the project

Arguments:

pathname: The pathname of the page (relative to the docs directory). It can be a plain filename, or a relative pathname. Please do not forget to add the extension (typically, '.md') content: The page content, as a string (Markdown with HTML, etc.). To facilitate the entry on a multiline string, the text is automatically aligned to the left margin (but keeping the indentations). meta: The metadata that must go into the YAML page header.

Returns:

The full page content with YAML front matter, as written to file.

build(strict=False, verbose=False)

Build the documentation, to perform the tests (equivalent to mkdocs build). Running a build is necessary so that the tests can be performed.

Parameters:

Name Type Description Default
strict bool

to make the build fail in case of warnings

 False
verbose bool

to generate the target_files directory

 False

Returns:

Type Description
CompletedProcess

(if desired) the low level result of the process (return code and stderr).

CompletedProcess

This info is generally not needed, since, those values are stored, and parsed.

clear()

Clear the docs source directory (and its subdirectories).

Returns:

Type Description
int

Number of files removed.

Raises:

Type Description
FileNotFoundError

If the documentation source directory does not exist.

delete()

Deletes the project dir and self.

Do NOT confuse with self.clear()!

USE with caution, this deletes ALL files of the mkdocs project, including the directory. The object becomes inoperable.

find_entries(title='', source='', severity='')

Filter entries according to criteria of title and severity; all criteria are case-insensitive.

Parameters:

Name Type Description Default
title str

regex

 ''
source str

regex, for which entity issued it (macros, etc.)

 ''
severity str

one of the existing sevirities

 ''

find_entry(title='', source='', severity='')

Find the first entry according to criteria of title and severity. Return None is not found.

Parameters:

Name Type Description Default
title str

regex

 ''
source str

regex

 ''
severity str

the severity, e.g. DEBUG, INFO, WARNING

 ''

get_page(name)

Find a page with its name in the list of Markdown pages (filenames). If not found, return None

Parameters:

Name Type Description Default
name str

a page name (full or partial, with or without extension).

 required

get_plugin(name)

Get a plugin config (from the Config file) by its plugin name

make_config(content='', filename='mkdocs.yml', **kwargs)

Creates a config file (YAML, prettyfied) for the mkdocs project. It will make sure that the test plugin is defined.

Arguments

content : str The YAML content as a string (to be parsed and merged). To facilitate the entry on a multiline string, the text is automatically aligned to the left margin (but keeping the indentations). filename : str The filename of the config file. **kwargs : Arguments interpreted as entries in the YAML file. These will precede the parsed content.

Example

yaml = MyProject.make_config(site_name='My project', theme='mkdocs', plugins=['search'])

Returns

str The final YAML configuration as written to disk.

self_check()

Performs a number of post-build self-checks (integrity)

Class: MkDocsPage

Bases: SuperDict

A markdown page from MkDocs, with all its information (source, target)

h1 property

First h1 in the markdown

html property

The final HTML code that will be displayed, complete with javascript, etc. (the end product).

plain_text property

The content, as plain text

soup property

Parsed content of the HTML page (as published).

Returns:

Type Description
BeautifulSoup

Soup object from BeautifulSoup

source property

The source information, drawn from the source file (it contains the original markdown, before any rendering).

Attributes:

Name Type Description
text

the source text (the full page, as actually typed)
markdown

the markdown part of the source text
frontmatter

the YAML frontmatter of the page (as a string)
meta

the parsed YAML front matter (as a dictionary)

find(tag, *args, **kwargs)

Extracts the first tag from the HTML source. It wraps the soup.find() function of BeautifulSoup. See: doc.

find_all(tag, *args, **kwargs)

Extract tags from the HTML source and return them with their attributes and content.

It wraps the soup.find_all() function of BeautifulSoup.

For args and *kwargs see documentation

Parameters:

Name Type Description Default
tag str

the string argument of soup.find_all(), i.e. the tag

 required

Returns:

Type Description
List[Tag]

Each tag returned in the list contains in particular
List[Tag]

attrs (a dictionary of the attributes)

List[Tag]

and string (the text within the tag,
List[Tag]

but None if there are nested tags).
Note

For various ways of formulating the query: see doc

find_header(pattern, header_level=None)

Finds a header in the

Returns:

Type Description
str

The first header (h1, h2, h3...) that matches a pattern;
str

otherwise None

find_text(pattern, header=None, header_level=None)

Find a text or regex pattern in the html page (case-insensitive).

Parameters:

Name Type Description Default
pattern str

the text or regex

 required
header text or regex

if specified, it finds it first, and then looks for the text between that header and the next one (any level).

 None
header_level int

you can speciy it, if there is a risk of ambiguity.

 None

Returns:

Type Description
str

The line where the pattern was found, or None

is_dest_file()

Predicate: does the destination file (HTML) exist?

is_markdown_rendered()

Predicate: "Rendered" means that the raw Markdown is different from the source markdown; more accurately, that the source markdown is not contained in the target markdown.

Please do NOT confuse this with the rendering of Markdown into HTML (with templates containing navigation, header and footer, etc.).

Hence "not rendered" is a "nothing happened".

It covers these cases:

  1. No rendering of the markdown has taken place at all (no plugin, or plugin inactive, or not instructions within the page).
  2. A header and/or footer were added to the Markdown code (in on_pre_page_macros() or in on_post_page_macro() in Mkdocs-Macros) but the Markdown itself was not modified.
  3. An order to render was given, but there was actually NO rendering of the markdown, for some reason (error case).

is_src_file()

Predicate: does the source (Markdown) file exist?

Class: LogEntry

This Dataclass describes the attributes of a log entry.

Bases: object

Represents a log entry

payload = None class-attribute instance-attribute

Payload of the entry (following lines, not starting with DEBUG, INFO, WARNING)

severity instance-attribute

Severity (DEBUG, INFO, WARNING)

source = None class-attribute instance-attribute

Source, if available (e.g. [macros])

title = None class-attribute instance-attribute

Title, first line

Function: lorem_ipsum()

mkdocs_test.lorem_ipsum(paragraphs=1, indent='', width=60)

Generates wrapped Lorem Ipsum pagraphs with:

  • Only the very first line unindented
  • indent (string of blank spaces) applied to all other lines
  • One blank line between paragraphs

Parameters:

Name Type Description Default
paragraphs int

the no of paragraphs required.

 1
indent str

the indentation for the second line and the next ones.

 ''
width int

the width of a line

 60

Returns:

Type Description
str

Paragraphs of Lorem Ipsum text, optionally indented from the second line.