pax_global_header 0000666 0000000 0000000 00000000064 14707761270 0014525 g ustar 00root root 0000000 0000000 52 comment=009a4207304b8dfdb5cdfe0398eaa9cccb00cf6a
mkdocs-test-0.5.3/ 0000775 0000000 0000000 00000000000 14707761270 0013767 5 ustar 00root root 0000000 0000000 mkdocs-test-0.5.3/.gitignore 0000664 0000000 0000000 00000000725 14707761270 0015763 0 ustar 00root root 0000000 0000000 # Temporary files
*~
.py~
.python-version
#Byte-compiled led / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class
# Distribution / packaging
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST
# MkDocs
site/
# Mkdocs-Test, Mkdocs-Macros and others
__*/
# Other files (generated by mkdocs-macros or others)
cache*
# JetBrains PyCharm and other IntelliJ based IDEs
.idea/
mkdocs-test-0.5.3/LICENSE 0000664 0000000 0000000 00000002065 14707761270 0014777 0 ustar 00root root 0000000 0000000 MIT License
Copyright (c) 2024 Laurent Franceschetti
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. mkdocs-test-0.5.3/README.md 0000664 0000000 0000000 00000013433 14707761270 0015252 0 ustar 00root root 0000000 0000000

# A testing framework (plugin + test fixture)
for MkDocs projects
- [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)
## 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**
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**
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**
`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 mkdocs-test-0.5.3/cleanup.sh 0000775 0000000 0000000 00000000730 14707761270 0015755 0 ustar 00root root 0000000 0000000 #!/bin/bash
# This is necessary to start from a clean version for test
# Find and delete all __pycache__ directories
find . -type d -name "__pycache__" -exec rm -rf {} +
# Find and delete all directories starting with __
find . -type d -name "__*" -exec rm -rf {} +
# Find and delete all .egg-info directories
find . -type d -name "*.egg-info" -exec rm -rf {} +
# Find and delete all .egg files
find . -type f -name "*.egg" -exec rm -f {} +
echo "Cleanup complete!"
mkdocs-test-0.5.3/logo.png 0000664 0000000 0000000 00000026343 14707761270 0015445 0 ustar 00root root 0000000 0000000 PNG
IHDR A bo pHYs + iTXtXML:com.adobe.xmp
Mkdocs-Test - 1
2024-10-08
32b1917c-8997-4549-8456-cfb6169cf6c3
525265914179580
2
Fralau
Canva (Renderer)
O1 'IDATxwxTe?LIB$Ti(,M)*`k}AW]ۺ.XTVP EzIH2df13!ɔ$0 a\W. '{TUU@P|' AKC@ u(A8
@P!@ A@ u(A8
@P!@ A{]F'$'E*AvK QEUT0U$#齩
EQ tZjՓ$ UHV@