{"id":21528505,"url":"https://github.com/fralau/mkdocs-test","last_synced_at":"2025-04-09T23:42:35.606Z","repository":{"id":257820286,"uuid":"869696842","full_name":"fralau/mkdocs-test","owner":"fralau","description":"A framework for testing MkDocs projects","archived":false,"fork":false,"pushed_at":"2024-11-04T06:02:15.000Z","size":204,"stargazers_count":5,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-03T10:50:06.828Z","etag":null,"topics":["mkdocs","plugin","testing-framework"],"latest_commit_sha":null,"homepage":"https://mkdocs-test-plugin.readthedocs.io/en/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fralau.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-08T18:21:01.000Z","updated_at":"2025-04-01T00:25:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"f3dbb8a2-9b7c-479c-a843-18081e7d5fb8","html_url":"https://github.com/fralau/mkdocs-test","commit_stats":null,"previous_names":["fralau/mkdocs-test"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fralau%2Fmkdocs-test","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fralau%2Fmkdocs-test/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fralau%2Fmkdocs-test/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fralau%2Fmkdocs-test/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fralau","download_url":"https://codeload.github.com/fralau/mkdocs-test/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248131470,"owners_count":21052819,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mkdocs","plugin","testing-framework"],"created_at":"2024-11-24T01:53:29.593Z","updated_at":"2025-04-09T23:42:35.576Z","avatar_url":"https://github.com/fralau.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n![MkDocs-Test](logo.png)\n\n#  A testing framework (plugin + test fixture)\u003cbr\u003efor MkDocs projects\n\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) \n![Language](https://img.shields.io/github/languages/top/fralau/mkdocs-test)\n![Github](https://img.shields.io/github/v/tag/fralau/mkdocs-test?label=github%20tag)\n![PyPI](https://img.shields.io/pypi/v/mkdocs-test)\n![Downloads](https://img.shields.io/pypi/dm/mkdocs-test) \n\n[View the documentation](https://mkdocs-test-plugin.readthedocs.io/en/latest/) on Read the Docs\n  \n\u003c/div\u003e\n\n\u003c!-- To update, run the following command:\nmarkdown-toc -i README.md \n--\u003e\n\n\u003c!-- toc --\u003e\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\u003c!-- tocstop --\u003e\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\u003e 📝 **Technical Note** \u003cbr\u003e The plugin exports the `nav` object,\n\u003e 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\u003e ⚠️ **The plugin is a pre-requisite** \u003cbr\u003e The framework will not work\n\u003e without the plugin (it exports the pages map into the\n\u003e `__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ïve 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\u003e ⚠️ **Two markdown versions** \u003cbr\u003e  `page.markdown`\n\u003e contains the markdown after possible transformations\n\u003e by plugins; whereas `page.source.markdown` contains the exact\n\u003e markdown in the file.\n\u003e\n\u003e If you wish to have the complete source file (including the frontmatter), \n\u003e 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ïve)\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffralau%2Fmkdocs-test","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffralau%2Fmkdocs-test","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffralau%2Fmkdocs-test/lists"}