Structured Documentation (#5)

Reviewed-on: #5
This commit is contained in:
Jürgen Edelbluth 2022-08-25 13:46:19 +02:00
parent 87ca957c68
commit 4eeeef5353
Signed by: git.codebau.dev
GPG Key ID: F798C6B4352E8035
53 changed files with 2456 additions and 176 deletions

11
CONTRIBUTING.md Normal file
View File

@ -0,0 +1,11 @@
Contributions are always welcome. There are different ways may help:
- Reporting bugs and errors
- Suggesting new features
- Improving code
- Improving documentation
- Implementing new features
The instance [git.codebau.dev](https://git.codebau.dev/) does not accept new registrations currently. Please contact me
under `csv_params`(at)`jued.de` if you have any contribution. We'll send you an invitation for the source code server or
find another way.

118
README.md
View File

@ -1,3 +1,5 @@
![pytest-csv-params](docs/icon/pytest-csv-params.png)
# pytest-csv-params
A pytest plugin to parametrize data-driven tests by CSV files.
@ -28,6 +30,11 @@ pip install pytest-csv-params
poetry add --dev pytest-csv-params
```
## Documentation / User Guide
**Detailed documentation can be found under
[docs.codebau.dev/pytest-plugins/pytest-csv-params/](https://docs.codebau.dev/pytest-plugins/pytest-csv-params/)**
## Usage: Command Line Argument
| Argument | Required | Description | Example |
@ -36,7 +43,7 @@ poetry add --dev pytest-csv-params
## Usage: Decorator
Simply decorate your test method with `@csv_params` and the following parameters:
Simply decorate your test method with `@csv_params` (`pytest_csv_params.decorator.csv_params`) and the following parameters:
| Parameter | Type | Description | Example |
|------------------|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
@ -47,43 +54,6 @@ Simply decorate your test method with `@csv_params` and the following parameters
| `data_casts` | `dict` (optional) | Cast Methods for the CSV Data (see "Data Casting" below) | `{ "a": int, "b": float }` |
| `header_renames` | `dict` (optional) | Replace headers from the CSV file, so that they can be used as parameters for the test function (since 0.3.0) | `{ "Annual Amount of Bananas": "banana_count", "Cherry export price": "cherry_export_price" }` |
## CSV File Lookup Order
CSV files are looked up following this rules:
- If the `data_file` parameter is an absolute path, this is used, regardless of the `base_dir` parameter or command line argument.
- If the `data_file` parameter is relative:
- If the `base_dir` parameter is set, the file is looked up there, regardless of the command line argument
- If the `base_dir` parameter is not set (or `None`):
- If the command line argument is set, the file is looked up there
- If the command line argument is not set, the file is looked up in the current working directory
## Data Casting
When data is read from CSV, they are always parsed as `str`. If you need them in other formats, you can set a method that should be called with the value.
These methods can also be lambdas, and are also good for further transformations.
### Data Casting Example
```python
from pytest_csv_params.decorator import csv_params
def normalize(x: str) -> str:
return x.strip().upper()
@csv_params(
data_file="/test/data.csv",
data_casts={
"col_x": normalize,
"col_y": float,
},
)
def test_something(col_x, col_y):
# Test something...
...
```
## CSV Format
The default CSV format is:
@ -93,31 +63,6 @@ The default CSV format is:
- If you need a `"` in the value, use `""` (double quote)
- Fields are separated by comma (`,`)
**The first line must contain the row names. Row names must match the parameters of the test method (except for an ID column that is configured as such -- see `id_col` decorator parameter).**
### Example CSV
```text
"ID#", "part_a", "part_b", "expected_result"
"first", 1, 2, 3
"second", 3, 4, 7
"third", 10, 11, 21
```
### Headers
The header line is very important, as it maps the values to parameters of the test function. The plugin supports you with that. The following rules apply:
- Every character that is not valid in a variable name is replaced by an underscore (`_`)
- If the character at the start is not a letter or an underscore, it is replaced by an underscore(`_`)
- If the name is still invalid then, because it's a keyword or a builtin name, an exception is raised (`CsvHeaderNameInvalid`)
If you don't want to change your CSV file, you can use the `header_renames` parameter to the decorator to rename headers as needed.
Headers must be unique, and an Exception is raised if not (`CsvHeaderNameInvalid`).
The header handling was heavily improved in Version 0.3.0.
## Usage Example
This example uses the CSV example from above.
@ -220,29 +165,12 @@ def test_container_size_is_big_enough(
...
```
## Breaking Changes
## Changelog
### Version 0.3.0
- A detailed changelog is here:
[docs.codebau.dev/pytest-plugins/pytest-csv-params/pages/changelog.html](https://docs.codebau.dev/pytest-plugins/pytest-csv-params/pages/changelog.html)
- Column header names that are reserved keywords or builtin names are no longer accepted. You should have been in trouble already if you used them, so nothing should go wrong with this change and existing tests.
### Version 0.2.0
- The parameter order for `pytest_csv_params.decorator.csv_params` changed to allow the shorthand usage with only a `data_file` as positional argument. If you used keyword arguments only (like the docs recommend), you will not run into trouble.
## Contributing
### Build and test
You need [Poetry](https://python-poetry.org/) in order to build this project.
Tests are implemented with `pytest`, and `tox` is used to orchestrate them for the supported python versions.
- Checkout this repo
- Run `poetry install`
- Run `poetry run tox` (for all supported python versions) or `poetry run pytest` (for your current version)
### Bugs etc.
## Bugs etc.
Please send your issues to `csv-params_issues` (at) `jued.de`. Please include the following:
@ -252,28 +180,16 @@ Please send your issues to `csv-params_issues` (at) `jued.de`. Please include th
It would be great if you could include example code that clarifies your issue.
### Pull Requests
See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
## Pull Requests
Pull requests are always welcome. Since this Gitea instance is not open to public, just send an e-mail to discuss options.
Any changes that are made are to be backed by tests. Please give me a sign if you're going to break the existing API and let us discuss ways to handle that.
### Quality Measures
Backed with pytest plugins:
- Pylint _(static code analysis and best practises)_
- black _(code formatting standards)_
- isort _(keep imports sorted)_
- Bandit _(basic static security tests)_
- mypy _(typechecking)_
Please to a complete pytest run (`poetry run pytest`), and consider running it on all supported platforms with (`poetry run tox`).
## License
Code is under MIT license. See `LICENSE.txt` for details.
See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
## Where are the sources?
The source code is available under [git.codebau.dev/pytest-plugins/pytest-csv-params](https://git.codebau.dev/pytest-plugins/pytest-csv-params).
The source code is available under [git.codebau.dev/pytest-plugins/pytest-csv-params](https://git.codebau.dev/pytest-plugins/pytest-csv-params).

View File

@ -1,14 +1,22 @@
"""
Command Line Options
This pytest plugin requires command line arguments that are parsed from the pytest framework. This module contains code
to instruct pytest to deliver the required values.
"""
from _pytest.config.argparsing import Parser
HELP_TEXT = "set base dir for getting CSV data files from"
"""
This is the help text for the command line arguments that is added by :meth:`pytest_addoption`.
"""
def pytest_addoption(parser: Parser, plugin_name: str = "csv-params") -> None:
"""
Add Command Line Arguments for pytest execution
Entrypoint for pytest to extend the own :class:`Parser` with the things we need extra.
:param parser: The pytest command line argument parser
:param plugin_name: The name of our plugin, with default value
"""
group = parser.getgroup(plugin_name)

View File

@ -1,6 +1,8 @@
"""
Pytest Plugin Configuration
The pytest plugin needs a setup (:meth:`pytest_configure`) and a teardown (:meth:`pytest_unconfigure`) method
registered. This module contains the required methods for that.
"""
from _pytest.config import Config
from _ptcsvp.plugin import Plugin
@ -9,6 +11,9 @@ from _ptcsvp.plugin import Plugin
def pytest_configure(config: Config, plugin_name: str = "csv_params") -> None:
"""
Register our Plugin
:param config: Pytets configuration class
:param plugin_name: The name of the pytest plugin, with default value
"""
config.pluginmanager.register(Plugin(config), f"{plugin_name}_plugin")
@ -16,5 +21,8 @@ def pytest_configure(config: Config, plugin_name: str = "csv_params") -> None:
def pytest_unconfigure(config: Config, plugin_name: str = "csv_params") -> None:
"""
Remove our Plugin
:param config: Pytest configuration class
:param plugin_name: The name of the pytest plgin, with default value
"""
config.pluginmanager.unregister(f"{plugin_name}_plugin")

View File

@ -22,7 +22,7 @@ from pytest_csv_params.types import BaseDir, CsvDialect, DataCasts, DataFile, He
class TestCaseParameters(TypedDict):
"""
Type for Test Case
Type for a single test case. Contains the optional :attr:`test_id` and the test :attr:`data`.
"""
test_id: Optional[str]
@ -32,6 +32,13 @@ class TestCaseParameters(TypedDict):
def read_csv(base_dir: BaseDir, data_file: DataFile, dialect: CsvDialect) -> List[List[str]]:
"""
Get Data from CSV
:param base_dir: Optional directory to look up non-absolute CSV files (given as :attr:`data_file`)
:param data_file: The CSV file to read. If this is an absolute path, :attr:`base_dir` will be ignored; if not, the
:attr:`base_dir` is prepended.
:param dialect: The CSV file dialect (definition of the format of a CSV file).
:returns: A list of rows, each row contains a list of columns; all type `str`
"""
if data_file is None:
@ -58,6 +65,14 @@ def read_csv(base_dir: BaseDir, data_file: DataFile, dialect: CsvDialect) -> Lis
def clean_headers(current_headers: List[str], replacing: HeaderRenames) -> List[str]:
"""
Clean the CSV file headers
:param current_headers: List of the current headers, as read from the CSV file (without the ID column, as far as it
exists)
:param replacing: Dictionary of replacements for headers
:returns: List of cleaned header names
:raises CsvHeaderNameInvalid: When non-unique names appear
"""
if replacing is not None:
for index, header in enumerate(current_headers):
@ -79,7 +94,18 @@ def add_parametrization( # pylint: disable=too-many-arguments
header_renames: HeaderRenames = None,
) -> MarkDecorator:
"""
Get data from the files and add things to the tests
Parametrize a test function with data from a CSV file.
For the public decorator, see :meth:`pytest_csv_params.decorator.csv_params`.
:param data_file: The CSV file to read the data from
:param base_dir: Optional base directory to look for non-absolute :attr:`data_file` in
:param id_col: Optional name of a column that shall be used to make the test IDs from
:param data_casts: Methods to cast a column's data into a format that is required for the test
:param dialect: The CSV file dialect (CSV file format) to use
:param header_renames: A dictonary mapping the header names from the CSV file to usable names for the tests
:returns: :meth:`pytest.mark.parametrize` mark decorator, filled with all the data from the CSV.
"""
if base_dir is None:
base_dir = getattr(Plugin, BASE_DIR_KEY, None)

View File

@ -1,19 +1,27 @@
"""
The main Plugin implementation
This module contains the main plugin class. By the time of writing, it is quite unspectacular.
"""
from _pytest.config import Config
BASE_DIR_KEY = "__pytest_csv_plugins__config__base_dir"
BASE_DIR_KEY = "__pytest_csv_params__config__base_dir"
"""
The class attribute key for :class:`Plugin` to store the base dir command line argument value.
"""
class Plugin: # pylint: disable=too-few-public-methods
"""
Plugin Class
The main plugin class
Currently, this class is nothing more than the keeper of the value of the command line argument (as defined by
:meth:`_ptcsvp.cmdline.pytest_addoption`.
"""
def __init__(self, config: Config) -> None:
"""
Hold the pytest config
Initialize the class, and simply store the value of the command line argument, as class attribute.
:param config: Pytest configuration
"""
setattr(Plugin, BASE_DIR_KEY, config.option.csv_params_base_dir)

View File

@ -1,5 +1,5 @@
"""
Test if a variable name is valid
This module contains code to validate variable/argument/parameter names or to make them valid ones.
"""
import builtins
@ -10,12 +10,22 @@ from string import ascii_letters, digits
from pytest_csv_params.exception import CsvHeaderNameInvalid
VALID_CHARS = ascii_letters + digits
"""
Valid characters a variable/parameter/argument name can consist of
"""
VARIABLE_NAME = re.compile(r"^[a-zA-Z_][A-Za-z0-9_]{0,1023}$")
"""
Regular expression that defines a valid variable/parameter/argument name
"""
def is_valid_name(name: str) -> bool:
"""
Checks if the variable name is valid
:param name: The name to be checked
:returns: `True`, when the name is valid
"""
if (
keyword.iskeyword(name)
@ -28,7 +38,12 @@ def is_valid_name(name: str) -> bool:
def make_name_valid(name: str, replacement_char: str = "_") -> str:
"""
Make a name valid
Make a name a valid name by replacing invalid chars with the as :attr:`replacement_char` given char
:param name: The name to make a valid one
:param replacement_char: The char to replace invalid chars with, default is an underscore `_`
:returns: A valid name
:raises CsvHeaderNameInvalid: If the fixed name is still an invalid name
"""
fixed_name = name

View File

@ -1,5 +1,8 @@
"""
Check Version Information
This module contains two methods to check if the python version is recent enough (:meth:`check_python_version`) and if
the pytest version is recent enough (:meth:`check_pytest_version`).
During the setup phase of the plugin (see :mod:`pytest_csv_params.plugin`) these methods are called.
"""
import sys
from typing import Tuple
@ -11,6 +14,9 @@ from packaging.version import parse
def check_python_version(min_version: Tuple[int, int] = (3, 8)) -> None:
"""
Check if the current version is at least 3.8
:param min_version: The minimum version required, as tuple, default is 3.8
:raises PythonTooOldError: When the python version is too old/unsupported
"""
if sys.version_info < min_version:
@ -20,6 +26,9 @@ def check_python_version(min_version: Tuple[int, int] = (3, 8)) -> None:
def check_pytest_version(min_version: Tuple[int, int] = (7, 1)) -> None:
"""
Check if the current version is at least 7.1
:param min_version: The minimum version required, as tuple, default is 7.1
:raises RuntimeError: When the pytest version is too old/unsupported
"""
from pytest import __version__ as pytest_version # pylint: disable=import-outside-toplevel

20
docs/Makefile Normal file
View File

@ -0,0 +1,20 @@
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = .
BUILDDIR = ../dist/docs
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

0
docs/_static/.gitkeep vendored Normal file
View File

40
docs/_toc.rst Normal file
View File

@ -0,0 +1,40 @@
Sitemap
=======
.. toctree::
:maxdepth: 1
:caption: Basics
pages/install
pages/guide
.. toctree::
:maxdepth: 1
:caption: Advanced Usage
pages/config
pages/examples
.. toctree::
:maxdepth: 1
:caption: Developers
pages/developer
pages/api
.. toctree::
:maxdepth: 1
:caption: Project Information
pages/changelog
pages/license
pages/issues
pages/contributing
.. toctree::
:maxdepth: 1
:caption: Meta
genindex
🌍 Project Page <https://git.codebau.dev/pytest-plugins/pytest-csv-params>
🌍 juergen.rocks <https://juergen.rocks/>

112
docs/conf.py Normal file
View File

@ -0,0 +1,112 @@
# pylint: skip-file
# mypy: ignore-errors
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
import sys
from os.path import abspath, dirname, join
import tomli
sys.path.insert(0, abspath(join(dirname(__file__), "..")))
# sys.path.insert(0, abspath(join(dirname(__file__), "..", "tests")))
# sys.path.insert(0, abspath(join(dirname(__file__), "..", "_ptcsvp")))
# sys.path.insert(0, abspath(join(dirname(__file__), "..", "pytest_csv_params")))
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
project = "pytest-csv-params"
copyright = "2022, Jürgen Edelbluth"
author = "Jürgen Edelbluth"
# release = "0.0.0"
with open(abspath(join(dirname(__file__), "..", "pyproject.toml")), "rt", encoding="utf-8") as pyproject_toml:
toml_data = tomli.loads(pyproject_toml.read())
release = toml_data["tool"]["poetry"]["version"]
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
extensions = [
"sphinx.ext.intersphinx",
"sphinx.ext.duration",
"sphinx.ext.doctest",
"sphinx.ext.autodoc",
"sphinx.ext.autosummary",
"sphinx.ext.napoleon",
"sphinx_autodoc_typehints",
"myst_parser",
]
intersphinx_mapping = {
"python": ("https://docs.python.org/3", (None, "python-inv.txt")),
"pytest": ("https://docs.pytest.org/en/7.1.x/", (None, "pytest-inv.txt")),
}
templates_path = ["_templates"]
exclude_patterns = []
source_suffix = {
".rst": "restructuredtext",
".txt": "markdown",
".md": "markdown",
}
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_theme = "sphinx_material"
html_static_path = ["_static"]
html_title = "pytest-csv-params Documentation"
html_short_title = "pytest-csv-params"
html_logo = "icon/pytest-csv-params.png"
pygments_style = "emacs"
# Material theme options (see theme.conf for more information)
html_theme_options = {
# Set the name of the project to appear in the navigation.
"nav_title": "Pytest CSV Params Plugin",
# Set you GA account ID to enable tracking
"google_analytics_account": None,
# Specify a base_url used to generate sitemap.xml. If not
# specified, then no sitemap will be built.
"base_url": None,
# Set the color and the accent color
"color_primary": "teal",
"color_accent": "deep-orange",
"repo_url": "https://git.codebau.dev/pytest-plugins/pytest-csv-params",
"repo_name": "git.codebau.dev",
"repo_type": None,
# Visible levels of the global TOC; -1 means unlimited
"globaltoc_depth": 1,
# If False, expand all TOC entries
"globaltoc_collapse": True,
# If True, show hidden TOC entries
"globaltoc_includehidden": False,
"css_minify": True,
"html_minify": True,
"master_doc": True,
}
myst_enable_extensions = [
"colon_fence",
]
html_sidebars = {
"**": [
"logo-text.html",
"globaltoc.html",
"localtoc.html",
"searchbox.html",
]
}
autodoc_typehints_format = "fully-qualified"
autodoc_preserve_defaults = True

2
docs/genindex.rst Normal file
View File

@ -0,0 +1,2 @@
Index
=====

Binary file not shown.

After

Width:  |  Height:  |  Size: 40 KiB

38
docs/index.md Normal file
View File

@ -0,0 +1,38 @@
```{image} icon/pytest-csv-params.png
:alt: Logo, shows a data table with an arrow to a test tube
:class: bg-primary
:width: 256px
:align: center
```
----
# Data-driven test parametrization für pytest with CSV files
[![PyPI - Downloads](https://img.shields.io/pypi/dw/pytest-csv-params?label=PyPI%20downloads&style=for-the-badge)](https://pypi.org/project/pytest-csv-params/)
[![PyPI - Version](https://img.shields.io/pypi/v/pytest-csv-params?label=PyPI%20version&style=for-the-badge)](https://pypi.org/project/pytest-csv-params/)
[![PyPI - Status](https://img.shields.io/pypi/status/pytest-csv-params?label=PyPI%20status&style=for-the-badge)](https://pypi.org/project/pytest-csv-params/)
[![PyPI - Format](https://img.shields.io/pypi/format/pytest-csv-params?label=PyPI%20format&style=for-the-badge)](https://pypi.org/project/pytest-csv-params/)
This pytest plugin allows you to parametrize your pytest tests by CSV files. Manage your test data independently of
your tests. This site guides you through [installation](pages/install) and [usage](pages/guide).
The plugin is [open source](https://git.codebau.dev/pytest-plugins/pytest-csv-params) and
[released under MIT license](pages/license).
It is listed in the [Python Package Index (PyPI)](https://pypi.org/project/pytest-csv-params/).
Your feedback, bug reports, improvements are appreciated! Get in touch via e-mail: `csv_params`@`jued`.`de`. Together
we'll find a way for your contribution.
----
```{eval-rst}
.. include:: _toc.rst
```
----
```{note}
This project is not affiliated with the pytest project, but heavily relies on it. Visit [pytest.org](https://pytest.org)
for more information about this great testing framework.
```

35
docs/make.bat Normal file
View File

@ -0,0 +1,35 @@
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=.
set BUILDDIR=..\dist\docs
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.https://www.sphinx-doc.org/
exit /b 1
)
if "%1" == "" goto help
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
:end
popd

View File

@ -0,0 +1,67 @@
# Private Elements
## Command Line Arguments
**Module:** `_ptcsvp.cmdline`
```{eval-rst}
.. automodule:: _ptcsvp.cmdline
:members:
:private-members:
:undoc-members:
```
## Plugin Configuration
**Module:** `_ptcsvp.configure`
```{eval-rst}
.. automodule:: _ptcsvp.configure
:members:
:private-members:
:undoc-members:
```
## The Parametrization
**Module:** `_ptcsvp.parametrize`
```{eval-rst}
.. automodule:: _ptcsvp.parametrize
:members:
:private-members:
:undoc-members:
```
## The Plugin Class
**Module:** `_ptcsvp.plugin`
```{eval-rst}
.. automodule:: _ptcsvp.plugin
:members:
:private-members:
:undoc-members:
```
## The Variable Name Validation
**Module:** `_ptcsvp.varname`
```{eval-rst}
.. automodule:: _ptcsvp.varname
:members:
:private-members:
:undoc-members:
```
## The Version Checks
**Module:** `_ptcsvp.version`
```{eval-rst}
.. automodule:: _ptcsvp.version
:members:
:private-members:
:undoc-members:
```

View File

@ -0,0 +1,49 @@
# Public Elements
## The Decorator
**Module:** `pytest_csv_params.decorator`
```{eval-rst}
.. automodule:: pytest_csv_params.decorator
:members:
:undoc-members:
```
## The CSV Dialect
**Module:** `pytest_csv_params.dialect`
```{eval-rst}
.. automodule:: pytest_csv_params.dialect
:members:
```
## The Exceptions
**Module:** `pytest_csv_params.exception`
```{eval-rst}
.. automodule:: pytest_csv_params.exception
:members:
```
## Plugin Code
**Module:** `pytest_csv_params.plugin`
```{eval-rst}
.. automodule:: pytest_csv_params.plugin
:members:
:undoc-members:
```
## Types
**Module:** `pytest_csv_params.types`
```{eval-rst}
.. automodule:: pytest_csv_params.types
:members:
:undoc-members:
```

127
docs/pages/api-ref/tests.md Normal file
View File

@ -0,0 +1,127 @@
# Tests
This page should give you an overview over all tests for this plugin.
## Global `conftest.py`
**Module:** `tests.conftest`
```{eval-rst}
.. automodule:: tests.conftest
:members:
:private-members:
:undoc-members:
```
## Standard Tests
```{eval-rst}
.. automodule:: tests.test_clean_headers
:members:
:private-members:
:undoc-members:
```
```{eval-rst}
.. automodule:: tests.test_parametrize
:members:
:private-members:
:undoc-members:
```
```{eval-rst}
.. automodule:: tests.test_read_csv
:members:
:private-members:
:undoc-members:
```
```{eval-rst}
.. automodule:: tests.test_varname
:members:
:private-members:
:undoc-members:
```
```{eval-rst}
.. automodule:: tests.test_version_check
:members:
:private-members:
:undoc-members:
```
## Plugin Tests
These tests test the plugin code by inserting the plugin into a test pytest instance.
### Plugin `conftest.py`
**Module:** `tests.plugin.conftest`
```{eval-rst}
.. automodule:: tests.plugin.conftest
:members:
:private-members:
:undoc-members:
```
### Tests
```{eval-rst}
.. automodule:: tests.plugin.test_cmd_line
:members:
:private-members:
:undoc-members:
```
```{eval-rst}
.. automodule:: tests.plugin.test_plugin
:members:
:private-members:
:undoc-members:
```
## POC Tests
### POC `conftest.py`
**Module:** `tests.poc.conftest`
```{eval-rst}
.. automodule:: tests.poc.conftest
:members:
:private-members:
:undoc-members:
```
### Tests
```{eval-rst}
.. automodule:: tests.poc.test_parametrize_with_generator
:members:
:private-members:
:undoc-members:
```
## Examples
```{eval-rst}
.. automodule:: tests.test_docs_example
:members:
:private-members:
:undoc-members:
```
```{eval-rst}
.. automodule:: tests.test_blog_example
:members:
:private-members:
:undoc-members:
```
```{eval-rst}
.. automodule:: tests.test_complex_example
:members:
:private-members:
:undoc-members:
```

11
docs/pages/api.md Normal file
View File

@ -0,0 +1,11 @@
# API Reference
The following documents are generated from the source code documentation.
```{toctree}
:maxdepth: 2
api-ref/public
api-ref/private
api-ref/tests
```

103
docs/pages/changelog.md Normal file
View File

@ -0,0 +1,103 @@
# Changelog
## Version 0.4.0
<u>Breaking Changes:</u> ✓ None
<u>Changes:</u>
- Structured Documentation (see source folder `docs/`), it is an important milestone to version 1.0; published under:
[docs.codebau.dev/pytest-plugins/pytest-csv-params](https://docs.codebau.dev/pytest-plugins/pytest-csv-params)
- Documentation widely extended with a lot of extra information
- A more detailed changelog as part of this documentation
- Some source code / API documentation
- `README.md` reduced in favor of the structured documentation
[Downloads](https://git.codebau.dev/pytest-plugins/pytest-csv-params/releases/tag/v0.4.0) |
[Technical Changelog](https://git.codebau.dev/pytest-plugins/pytest-csv-params/compare/v0.3.0...v0.4.0)
## Version 0.3.0
<u>Breaking Changes:</u>
- Column names are now tested for reserved names. If you used reserved names in the past, this might break your tests,
despite the fact, that you are greater trouble already.
<u>Changes:</u>
- Much better handling of column names (headers) in CSV files:
- Invalid characters are replaced by a `_`
- Names are checked if they are reserved keywords or builtin names
- A new parameter `header_renames` to the decorator `@csv_params` allows you to bring your CSV column names to clean
variable names
- See `README.md` for further details
[Downloads](https://git.codebau.dev/pytest-plugins/pytest-csv-params/releases/tag/v0.3.0) |
[Technical Changelog](https://git.codebau.dev/pytest-plugins/pytest-csv-params/compare/v0.2.2...v0.3.0)
## Version 0.2.2
<u>Breaking Changes:</u> ✓ None
<u>Changes:</u>
- Library updates
- For Developers: Added a few extra tests for base functionality of pytest that is used in this plugin.
[Downloads](https://git.codebau.dev/pytest-plugins/pytest-csv-params/releases/tag/v0.2.2) |
[Technical Changelog](https://git.codebau.dev/pytest-plugins/pytest-csv-params/compare/v0.2.0...v0.2.2)
## Version 0.2.0
<u>Breaking Changes:</u>
- The order of the parameters for the decorator `@csv_params` changed to realize the new shorthand form of the decorator
(see below). If you used the decorator with keyword parameters only (like it is written in the documentation), you are
fine.
<u>Changes</u>
- New shorthand form for the decorator `@csv_params`. This is very handy when you have CSV files with no ID column and
column names that match the test functions parameters names. Together with the command line parameter introduced in
version 0.1.0 you can create very short decorators. See `README.md` for details.
- For Developers: Mypy has been added to the test chain for typing analysis
[Downloads](https://git.codebau.dev/pytest-plugins/pytest-csv-params/releases/tag/v0.2.0) |
[Technical Changelog](https://git.codebau.dev/pytest-plugins/pytest-csv-params/compare/v0.1.0...v0.2.0)
## Version 0.1.0
<u>Breaking Changes:</u> ✓ None
<u>Changes:</u>
- A new command line argument `--csv-params-base-dir` allows you to set a base dir for all relative CSV files. This is
great when you have a central storage for your test data. See `README.md` for more details.
- Some documentation fixes
- Some changes to the tox configuration in order to report coverage correctly
[Downloads](https://git.codebau.dev/pytest-plugins/pytest-csv-params/releases/tag/v0.1.0) |
[Technical Changelog](https://git.codebau.dev/pytest-plugins/pytest-csv-params/compare/v0.0.4...v0.1.0)
## Version 0.0.4
<u>Breaking Changes:</u> ✓ None
<u>Changes:</u>
- Minor documentation bugfixes
[Downloads](https://git.codebau.dev/pytest-plugins/pytest-csv-params/releases/tag/v0.0.4) |
[Technical Changelog](https://git.codebau.dev/pytest-plugins/pytest-csv-params/compare/v0.0.3...v0.0.4)
## Version 0.0.3
<u>Breaking Changes:</u> ✓ None
<u>Changes:</u>
- Initial Public Release
- Delivered the `@csv_params` decorator
[Downloads](https://git.codebau.dev/pytest-plugins/pytest-csv-params/releases/tag/v0.0.3) |
[Technical Changelog](https://git.codebau.dev/pytest-plugins/pytest-csv-params/compare/v0.0.2...v0.0.3)

254
docs/pages/config.md Normal file
View File

@ -0,0 +1,254 @@
# Configuration
## Decorator Parameters
These are the parameters for the decorator {meth}`pytest_csv_params.decorator.csv_params`.
### Overview
| Parameter | Type | Description | Example |
|------------------|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| `data_file` | `str` | The CSV file to use, relative or absolute path | `"/var/testdata/test1.csv"` |
| `base_dir` | `str` (optional) | Directory to look up relative CSV files (see `data_file`); overrides the command line argument | `join(dirname(__file__), "assets")` |
| `id_col` | `str` (optional) | Column name of the CSV that contains test case IDs | `"ID#"` |
| `dialect` | `csv.Dialect` (optional) | CSV Dialect definition (see [Python CSV Documentation](https://docs.python.org/3/library/csv.html#dialects-and-formatting-parameters)) | `csv.excel_tab` |
| `data_casts` | `dict` (optional) | Cast Methods for the CSV Data (see "Data Casting" below) | `{ "a": int, "b": float }` |
| `header_renames` | `dict` (optional) | Replace headers from the CSV file, so that they can be used as parameters for the test function (since 0.3.0) | `{ "Annual Amount of Bananas": "banana_count", "Cherry export price": "cherry_export_price" }` |
### Detailed Description
#### `data_file`
This points to the CSV file to load for this test. You can use relative or absolute paths. If you use a relative path
and a `base_dir`, the `base_dir` is prepended to the `data_file`.
````{admonition} Hint
It's a good idea to put your CSV data files in a `test-assets` folder on the same level than your `test_something.py`
file.
Example Layout:
```text
tests/
+- test-assets/
| +- case1.csv
| +- case2.csv
+- test_case1.py
+- test_case2.py
```
Now use this for `data_file` and `base_dir` (in one of the `test_caseX.py`):
```python
from os.path import dirname, join
from pytest_csv_params.decorator import csv_params
@csv_params(data_file="case1.csv", base_dir=join(dirname(__file__), "test-assets"))
def test_case1():
...
```
````
#### `base_dir`
This is an optional parameter. Set it to the directory where the CSV file from the `data_file` parameter should be
looked up. If not `None` (which is the default value), the value will be prepended to the `data_file` value, as long as
`data_file` is not an absolute path.
See `--csv-params-base-dir` command line argument below also.
```{warning}
Setting `base_dir` to something that is not `None` overrides anything that is set by the `--csv-params-base-dir`
command line argument.
```
#### `id_col`
Name the column that contains the test case IDs. If `None` (which is the default value), no test case IDs will be
generated. In this case, pytest will create its own IDs based on the parameters for the test. The column name does not
need to be valid variable/argument name.
Example:
```text
"Test Case ID#", "val_a", "val_b"
"test-12 / 4", "1234", "4321"
"test-13 / 7", "3210", "0123"
"test-14 / 9", "5432", "2345"
```
The test case ID is in the column "Test Case ID#". You'd configure it like this:
```python
from os.path import dirname, join
from pytest_csv_params.decorator import csv_params
@csv_params(data_file=join(dirname(__file__), "test-assets", "case1.csv"), id_col="Test Case ID#")
def test_case1(param_1: str, param_2: str) -> None:
...
```
#### `dialect`
Set the CSV dialect, it must be of the type {class}`csv.Dialect`. A dialect defines how a CSV file looks like.
The default dialect is {class}`pytest_csv_params.dialect.CsvParamsDefaultDialect`.
A dialect consists of the following settings:
| Setting | Default value in {class}`~pytest_csv_params.dialect.CsvParamsDefaultDialect` |
|---------------------------------------|------------------------------------------------------------------------------|
| {attr}`~csv.Dialect.delimiter` | `","` |
| {attr}`~csv.Dialect.doublequote` | `True` |
| {attr}`~csv.Dialect.escapechar` | `None` |
| {attr}`~csv.Dialect.lineterminator` | `"\r\n"` |
| {attr}`~csv.Dialect.quotechar` | `'"'` |
| {attr}`~csv.Dialect.quoting` | {data}`csv.QUOTE_ALL` |
| {attr}`~csv.Dialect.skipinitialspace` | `True` |
| {attr}`~csv.Dialect.strict` | `True` |
See [Usage Examples](examples) to learn how to create your own decorator that would always use your own specific CSV
file dialect.
```{note}
Regardless of the format parameters you are defining, all values from the CSV file are read as `str`. You may need to
convert them into other types. This is where `data_casts` are for.
```
#### `data_casts`
This dictionary allows you to setup methods to convert the string values from the CSV files into types or formats
required for test execution.
```{admonition} Rule of thumb
1. You can use any method that accepts a single `str` parameter. It can return anything you need.
2. If you need to test your test code, you should prefer conversion methods over conversion lambdas.
```
Example:
```text
"Test Case ID#", "val_a", "val_b", "val_c", "val_d", "val_e"
"test-12 / 4", "2.022", "152", "1 x 3", "abcd", "flox"
"test-13 / 7", "3.125", "300", "2 x 4", "defg", "trox"
"test-14 / 9", "4.145", "150", "3x6x9", "hijk", "bank"
```
- The values of column "Test Case ID#" do not need any conversion. The column will serve as `id_col`.
- The values of column "val_a" should be converted into `float`. Since `float` is also a method, it can be used
directly.
- The values of column "val_b" should be converted into `int`. Since `int` is also a method, it can be used directly.
- The values of column "val_c" must be converted a bit more complex. We'll use a `lambda` for that.
- The values of column "val_d" don't need to be converted. They are `str`.
- The values of column "val_e" will be converted with a helper method (`convert_val_e`).
Implementation of this example:
```python
from typing import List, Optional, Tuple
from pytest_csv_params.decorator import csv_params
def convert_val_e(value: str) -> Tuple[bool, Optional[str]]:
str_val = None
bool_val = value.endswith("ox")
if bool_val:
str_val = value[:2]
return bool_val, str_val
@csv_params(
data_file="test1.csv",
id_col="Test Case ID#",
data_casts={
"val_a": float,
"val_b": int,
"val_c": lambda x: list(map(lambda y: y.strip(), x.split("x"))),
"val_e": convert_val_e,
},
)
def test_something(val_a: float, val_b: int, val_c: List[int], val_d: str, val_e: Tuple[bool, Optional[str]]) -> None:
...
```
```{note}
In this example, the columns were named as valid argument/parameter names. So there's no need for `header_renames` here.
```
#### `header_renames`
This dictionary allows to rename the column headers into valid argument names for your test methods. The plugin will try
to rename invalid header names by replacing invalid chars with underscores, but this might not result in well-formed and
readable names.
Example:
```text
"Test Case ID#", "Flux Compensator Setting", "Power Level"
"101 / 885 / 31", "1-1-2-1-2-7-5-3-4-9/7", "100 %"
"109 / 995 / 21", "3-2-2-2-6-4-2-2-1-2/8", "15 %"
"658 / 555 / 54", "3-2-3-4-5-6-7-3-2-3/2", "25 %"
```
Configuration of the decorator:
```python
from pytest_csv_params.decorator import csv_params
@csv_params(
data_file="test.csv",
id_col="Test Case ID#",
header_renames={
"Flux Compensator Setting": "flux_setting",
"Power Level": "power_level",
},
)
def test_something_else(fux_setting: str, power_level: str) -> None:
...
```
```{warning}
`data_casts` dictionary keys must match the renamed column names!
```
## Command Line Arguments
These are the command line arguments for the pytest run.
### Overview
| Argument | Required | Description | Example |
|-------------------------|---------------|----------------------------------------------------------------------|----------------------------------------------|
| `--csv-params-base-dir` | no (optional) | Define a base dir for all relative-path CSV data files (since 0.1.0) | `pytest --csv-params-base-dir /var/testdata` |
### Detailed Description
#### `--csv-params-base-dir`
This is a convenience command line argument. It allows you to set a base directory for all your CSV parametrized test
cases. If you use relative `data_file`s, this can be automatically prepended. You can still override this setting per
test by using the `base_dir` configuration.
## How a CSV file is found
```text
+-----------------------------------+ /-----------------------------------\
| data_dir is absolute path? | --- yes --- | use this path |
+-----------------------------------+ \-----------------------------------/
|
no
|
+-----------------------------------+ /-----------------------------------\
| is a base_dir set on the test? | --- yes --- | prepend base_dir to data_file |
+-----------------------------------+ \-----------------------------------/
|
no
|
+-----------------------------------+ /-----------------------------------\
| is command line argument given? | --- yes --- | prepend arg value to data_file |
+-----------------------------------+ \-----------------------------------/
|
no
|
/-----------------------------------\
| use data_file as relative path |
\-----------------------------------/
```

View File

@ -0,0 +1,6 @@
# Contributing
```{eval-rst}
.. include:: ../../CONTRIBUTING.md
:parser: myst_parser.sphinx_
```

195
docs/pages/developer.md Normal file
View File

@ -0,0 +1,195 @@
# Developer Guide
If you want to develop for / with the Pytest CSV Params Plugin, consider to clone the repository:
```bash
git clone https://git.codebau.dev/pytest-plugins/pytest-csv-params.git
```
You need **Python 3.8** or newer.
The project's dependencies and building are managed by `poetry`. Please follow the instructions from
[python-poetry.org](https://python-poetry.org/) to install `poetry` on your system.
Install all the dependencies, including the development dependencies:
```bash
poetry install
```
## Commit Signing
Commit signing is mandatory for all commits for the `main` branch. Please make sure, your public key is set up and
registered with `git.codebau.dev`.
## Testing
Tests are implemented with `pytest`. You find them in the `tests` folder. Besides unit and integration tests, some other
checks are executed by `pytest` plugins:
- **`pytest-black`:** This plugin checks code formatting with [`black`](https://github.com/psf/black). If tests fail,
try `poetry run black .` from the project root to fix formatting issues. Configuration: `pyproject.toml`, section
`[tool.black]`.
- **`pytest-isort`:** This plugin checks import sorting with [`isort`](https://github.com/PyCQA/isort). If tests fail,
try `poetry run isort .` from the project root to fix import sorting issues. Configuration: `pyproject.toml`, section
`[tool.isort]`.
- **`pytest-pylint`:** This plugin does a static code analysis with [`pylint`](https://github.com/PyCQA/pylint). The
test configuration can be found in `.pylintrc` in the project root.
- **`pytest-bandit`:** This plugin performs a static security analysis of the code with
[`bandit`](https://github.com/PyCQA/bandit). The configuration is part of the `[tool.pytest.ini_options]` section in
the `pyproject.toml`, config keys `bandit_*`.
- **`pytest-mypy`:** This plugin uses [`mypy`](https://mypy.readthedocs.io/en/stable/) to perform typing checks against
the code. The configuration can be found in the `pyproject.toml`, section `[tool.mypy]`.
Most plugins are enabled by the `addopts` switches, configured in the `pyproject.toml`, section
`[tool.pytest.ini_options]`. Some plugins have extra configuration switches even there.
Additionally, the code coverage is measured by `pytest-cov` using [`coverage.py`](https://github.com/nedbat/coveragepy).
A high coverage alone is not a very good metric, but it helps to find and fix coverage weaknesses. The configuration for
coverage measurement is in the `pyproject.toml`, sections `[tool.coverage]`, `[tool.coverage.run]` and
`[tool.coverage.report]`.
There are some other pytest plugins installed and used for tests:
- **`pytest-mock`:** Simplified mocking
- **`pytest-clarity`:** Better output of assertion errors
- **`pytest-order`:** Execute tests in a given order (used in {mod}`tests.poc.test_parametrize_with_generator`).
### Test runs with `pytest`
Just run all the tests with:
```bash
poetry run pytest
```
### Test runs with `tox`
`tox` is used to execute all tests under the different supported Python versions. Make sure you installed all relevant
versions on your system, for example with [`pyenv`](https://github.com/pyenv/pyenv).
To execute them all, run:
```bash
poetry run tox
```
If you experience strange `tox` errors, try to recreate the `tox` environments:
```bash
poetry run tox -r
```
`tox` is configured in the `pyproject.toml`, section `[tool.tox]`.
```{admonition} No new or changed code without test
If you add or change code, please make sure your changes are covered by meaningful tests.
```
## Building
There are two different things to build from the source code: The **Wheel distribution package** from the Python code
and the **documentation**.
### Code
The publishing is done managed with `poetry`. The complete build and deploy configuration takes place in the
`pyproject.toml`. Besides the standard configuration in section `[tool.poetry]`, additional URLs are defined in section
`[tool.poetry.urls]`. As a speciality for this plugin, an entry point is defined in section
`[tool.poetry.plugins."pytest11"]`.
To build the packages, just run `poetry build` from the project root.
(build-docs)=
### Docs
The docs are in the `docs` folder. There is a `conf.py` that contains all the settings. Documentation is managed by
[`sphinx`](https://www.sphinx-doc.org/). There is a `make` file (`Makefile`) as well as a `make.bat`, they contain some
configuration also.
The `serve.py` scripts starts a live reload server to preview the documentation.
To build the documentation, run `poetry run make html` (respectively `poetry run make.bat html` on Windows) from the
`docs` directory.
## Publishing
```{warning}
The following section is more a reference for project members. If you not belong to the project, you'll not be able to
publish or update packages.
Maybe you find it helpful as a boiler plate for your own projects.
```
### Increase Version
If not already done, increase the version in the `pyproject.toml`. This can be done manually, but `poetry` offers a
helper for that:
| `poetry` command | Effect |
|------------------------|----------------|
| `poetry version patch` | increase patch |
| `poetry version minor` | increase minor |
| `poetry version major` | increase major |
### Complete Changelog
Update the `docs/pages/changelog.md` file with all relevant things happened since the last release. Set a compare link
and a link to the release page. You can set them up even if the release does not exist at the moment.
Don't forget to commit now!
### Tag the release
Set a git tag in the format `vX.Y.Z` (with the leading `v`). Push all your commits and the tag now.
### PyPI
```{admonition} Poetry configuration for publishing
If not already done, you need to setup `poetry` for publishing.
**1. Configuration for production PyPI**
- Get your token from [pypi.org](https://pypi.org/)
- Set your token with `poetry config pypi-token.pypi pypi-YOUR_PROD_TOKEN`
**2. Configuration for test PyPI**
- Get your token from [test.pypi.org](https://test.pypi.org/)
- Setup the test repo: `poetry config repositories.test.url https://test.pypi.org/legacy/`
- Set your token with `poetry config pypi-token.test pypi-YOUR_TEST_TOKEN`
**3. Configuration for Codebau Package Repository**
- Get your token from [git.codebau.dev](https://git.codebau.dev/)
- Setup the codebau repo:
`poetry config repositories.codebau.url https://git.codebau.dev/api/packages/pytest-plugins/pypi`
- Setup your token with `poetry config pypi-token.codebau YOUR_CODEBAU_TOKEN`
```
#### Publish to test.pypi.org
It's a good practice to publish a new package to [test.pypi.org](https://test.pypi.org/) first.
```bash
poetry publish --build -r test
```
You can omit the `--build` param when you already built the package.
#### Publish to production pypi.org
```bash
poetry publish --build
```
#### Publish to git.codebau.dev Package Repository
```bash
poetry publish --build -r codebau
```
### Documentation
The documentation is automatically build from the `main` branch and published to `docs.codebau.dev`. If you want to
build by yourself, see {ref}`Building / Docs <build-docs>`. You find the compiled docs under `dist/docs/html`.

25
docs/pages/examples.md Normal file
View File

@ -0,0 +1,25 @@
# Usage Examples
## Build your own annotation
Using another CSV format? The same `data_casts` methods each time? There is only one name for a test ID column? You can
easily build your own annotation. Just create a method that contains your common stuff:
```python
from pytest_csv_params.decorator import csv_params
def my_csv_params(data_file: str, **kwargs):
kwargs.setdefault("base_dir", "/var/test-data")
kwargs.setdefault("id_col", "Test Case ID")
kwargs.setdefault("header_renames", {
"Order #": "order_number",
"Price Total": "total_price",
})
kwargs.setdefault("data_casts", {
"total_price": float,
})
return csv_params(data_file, **kwargs)
```
When you now write a test, you can decorate it with `@my_csv_params("test-file-1.csv")`. You can override any of your
default settings by just adding it as a keyword argument: `@my_csv_params("test-file-1.csv", id_col="Test ID")`.

128
docs/pages/guide.md Normal file
View File

@ -0,0 +1,128 @@
# User Guide
This guide will lead you to your first CSV-file parametrized pytest test. It starts with designing your test, preparing
your data, writing the test method and finally execute your new test.
## The Scenario
Let's say, you have to test this method:
```{eval-rst}
.. literalinclude:: ../../tests/test_docs_example.py
:language: python
:lines: 10,12,18-23,37-41
```
Parts of the code are from a more complex example written for
[a German blog post](https://juergen.rocks/blog/articles/data-driven-tests-mit-pytest-csv-params.html). The example code
is part of the source code and can be found unter `tests/test_blog_example.py`. It is documented as
{mod}`~tests.test_blog_example`.
## Prepare your data
Your test data resides in an CSV file. CSV files can have different formats, when it comes to:
- Field separators and delimiters
- Quoting
- Line Termination
The class {class}`pytest_csv_params.dialect.CsvParamsDefaultDialect` defines a default CSV format that should fit most
requirements:
```{eval-rst}
.. literalinclude:: ../../pytest_csv_params/dialect.py
:language: python
:lines: 5-6,8,18-
```
You can derive your own CSV format class from there (or from {class}`csv.Dialect`), if your files look any other.
Your test data for the method above could look like this:
```{eval-rst}
.. literalinclude:: ../../tests/assets/doc-example.csv
:language: text
:emphasize-lines: 1
```
- We have a header line in the first line, that names the single columns
- The column names are not good for argument names
- The value in the dimensions column needs to be transformed in order to get tested
- There is a column that tells if an exception is to be expected, and the last two lines expect one
## Design and write the test
The test must call the ``get_smallest_possible_container`` method with the right parameters. The CSV file has all
information, but maybe not in the right format. We take care of that in a second.
The test may expect an exception, that should also be considered.
The parameters of the test method should reflect the input parameters for the method under test, and the expectations.
So let's build it:
```{eval-rst}
.. literalinclude:: ../../tests/test_docs_example.py
:language: python
:lines: 14-15,75-81,91-
:emphasize-lines: 4-8
```
- The test could now get all parameters needed to execute the `get_smallest_container_method`, as well as for the
expectations
- Based on the expectation for an exception, the test goes in two different directions
Now it's time for getting stuff from the CSV file.
## Add the parameters from the CSV file
Here comes the {meth}`~pytest_csv_params.decorator.csv_params` decorator. But one step after the other.
```{eval-rst}
.. literalinclude:: ../../tests/test_docs_example.py
:language: python
:lines: 14,16-17,58-81
:emphasize-lines: 5,6,8,16,18
```
- With the parameter `data_file` you point to your CSV file
- With the parameter `id_col` you name the column of the CSV file that contains the test case ID; the test case ID is
shown in the execution logs
- With the `header_renames` dictionary you define how a column is represented as argument name for your test method; the
highlighted example transforms "Number of items" to `number_of_items`
- The `data_casts` dictionary you define how data needs to be transformed to be usable for the test; you can use
`lambda`s or method pointers; all values from the CSV arrive as `str`
All possible parameters are explained under [Configuration](config), or more technically, in the source documentation of
{meth}`pytest_csv_params.decorator.csv_params`.
The `data_casts` method `get_dimensions` looks like the following:
```{eval-rst}
.. literalinclude:: ../../tests/test_docs_example.py
:language: python
:lines: 44,52-55
:emphasize-lines: 4
```
The method is called during the test collection phase. If the {class}`ValueError` raises, the run would end in an error.
## Execute the test
There is nothing special to do now. Just run your tests as always. Your run should look like this:
```text
tests/test.py::test_get_smallest_possible_container[Small Container 1] PASSED [ 12%]
tests/test.py::test_get_smallest_possible_container[Small Container 2] PASSED [ 25%]
tests/test.py::test_get_smallest_possible_container[Small Container 3] PASSED [ 37%]
tests/test.py::test_get_smallest_possible_container[Medium Container] PASSED [ 50%]
tests/test.py::test_get_smallest_possible_container[Large Container 1] PASSED [ 62%]
tests/test.py::test_get_smallest_possible_container[Large Container 2] PASSED [ 75%]
tests/test.py::test_get_smallest_possible_container[Not fitting 1] PASSED [ 87%]
tests/test.py::test_get_smallest_possible_container[Not fitting 2] PASSED [100%]
```
## Analyse test failures
- Is it a failure for all test data elements or just for a few?
- When only some tests fail, the Test ID should tell you where to look at

35
docs/pages/install.md Normal file
View File

@ -0,0 +1,35 @@
# Installation
There are serveral ways to install the package. The `pip` and the [`poetry`](https://python-poetry.org/) ways are
recommended.
The minimum requirements are:
- Python >= 3.8
- Pytest >= 7.1
The plugin should run anywhere where these two things can be used.
## Install via `pip`
```bash
pip install pytest_csv_params
```
Alternatively, you can use the codebau.dev package repository:
```bash
pip install --extra-index-url https://git.codebau.dev/api/packages/pytest-plugins/pypi/simple pytest-csv-params
```
## Install via `poetry`
```bash
poetry add --dev pytest_csv_params
```
For more information about `poetry`, visit [python-poetry.org](https://python-poetry.org/)
## For development
Please checkout the repository from [git.codebau.dev](https://git.codebau.dev/pytest-plugins/pytest-csv-params).

4
docs/pages/issues.md Normal file
View File

@ -0,0 +1,4 @@
# Issues
Please report issues to `csv_params-issues`(at)`jued.de`. We'll put them in our issue tracker under
[git.codebau.dev/pytest-plugins/pytest-csv-params/issues](https://git.codebau.dev/pytest-plugins/pytest-csv-params/issues).

9
docs/pages/license.md Normal file
View File

@ -0,0 +1,9 @@
# License
```{eval-rst}
.. literalinclude:: ../../LICENSE.txt
:language: text
```
The source code is published on [git.codebau.dev](https://git.codebau.dev/pytest-plugins/pytest-csv-params).
The `LICENSE.txt` file is in the repository root.

29
docs/serve.py Normal file
View File

@ -0,0 +1,29 @@
# pylint: skip-file
# mypy: ignore-errors
import sys
from os.path import dirname, join
from livereload import Server, shell
if __name__ == "__main__":
cmd = "make html"
if "win32" in sys.platform.lower():
cmd = "make.bat html"
server = Server()
project_dir = join(dirname(__file__), "..")
watch_dirs = [
join(project_dir, "pytest_csv_params", "**/*"),
join(project_dir, "_ptcsvp", "**/*"),
join(project_dir, "tests", "**/*"),
join(project_dir, "docs", "**/*"),
]
for watch_dir in watch_dirs:
server.watch(watch_dir, shell(cmd), delay=1)
server.serve(
root=join(project_dir, "dist", "docs", "html"),
host="127.0.0.1",
port="8000",
)

548
poetry.lock generated
View File

@ -1,3 +1,11 @@
[[package]]
name = "alabaster"
version = "0.7.12"
description = "A configurable sidebar-enabled Sphinx theme"
category = "dev"
optional = false
python-versions = "*"
[[package]]
name = "astroid"
version = "2.11.7"
@ -33,6 +41,17 @@ docs = ["furo", "sphinx", "zope.interface", "sphinx-notfound-page"]
tests = ["coverage[toml] (>=5.0.2)", "hypothesis", "pympler", "pytest (>=4.3.0)", "mypy (>=0.900,!=0.940)", "pytest-mypy-plugins", "zope.interface", "cloudpickle"]
tests_no_zope = ["coverage[toml] (>=5.0.2)", "hypothesis", "pympler", "pytest (>=4.3.0)", "mypy (>=0.900,!=0.940)", "pytest-mypy-plugins", "cloudpickle"]
[[package]]
name = "babel"
version = "2.10.3"
description = "Internationalization utilities"
category = "dev"
optional = false
python-versions = ">=3.6"
[package.dependencies]
pytz = ">=2015.7"
[[package]]
name = "bandit"
version = "1.7.4"
@ -52,6 +71,21 @@ test = ["coverage (>=4.5.4)", "fixtures (>=3.0.0)", "flake8 (>=4.0.0)", "stestr
toml = ["toml"]
yaml = ["pyyaml"]
[[package]]
name = "beautifulsoup4"
version = "4.11.1"
description = "Screen-scraping library"
category = "dev"
optional = false
python-versions = ">=3.6.0"
[package.dependencies]
soupsieve = ">1.2"
[package.extras]
html5lib = ["html5lib"]
lxml = ["lxml"]
[[package]]
name = "black"
version = "22.6.0"
@ -74,6 +108,25 @@ d = ["aiohttp (>=3.7.4)"]
jupyter = ["ipython (>=7.8.0)", "tokenize-rt (>=3.2.0)"]
uvloop = ["uvloop (>=0.15.2)"]
[[package]]
name = "certifi"
version = "2022.6.15"
description = "Python package for providing Mozilla's CA Bundle."
category = "dev"
optional = false
python-versions = ">=3.6"
[[package]]
name = "charset-normalizer"
version = "2.1.0"
description = "The Real First Universal Charset Detector. Open, modern and actively maintained alternative to Chardet."
category = "dev"
optional = false
python-versions = ">=3.6.0"
[package.extras]
unicode_backport = ["unicodedata2"]
[[package]]
name = "click"
version = "8.1.3"
@ -118,6 +171,14 @@ tomli = {version = "*", optional = true, markers = "python_full_version <= \"3.1
[package.extras]
toml = ["tomli"]
[[package]]
name = "css-html-js-minify"
version = "2.5.5"
description = "CSS HTML JS Minifier"
category = "dev"
optional = false
python-versions = ">=3.6"
[[package]]
name = "dill"
version = "0.3.5.1"
@ -137,6 +198,14 @@ category = "dev"
optional = false
python-versions = "*"
[[package]]
name = "docutils"
version = "0.18.1"
description = "Docutils -- Python Documentation Utilities"
category = "dev"
optional = false
python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*"
[[package]]
name = "filelock"
version = "3.8.0"
@ -171,6 +240,38 @@ python-versions = ">=3.7"
[package.dependencies]
gitdb = ">=4.0.1,<5"
[[package]]
name = "idna"
version = "3.3"
description = "Internationalized Domain Names in Applications (IDNA)"
category = "dev"
optional = false
python-versions = ">=3.5"
[[package]]
name = "imagesize"
version = "1.4.1"
description = "Getting image size from png/jpeg/jpeg2000/gif file"
category = "dev"
optional = false
python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*"
[[package]]
name = "importlib-metadata"
version = "4.12.0"
description = "Read metadata from Python packages"
category = "dev"
optional = false
python-versions = ">=3.7"
[package.dependencies]
zipp = ">=0.5"
[package.extras]
docs = ["sphinx", "jaraco.packaging (>=9)", "rst.linker (>=1.9)"]
perf = ["ipython"]
testing = ["pytest (>=6)", "pytest-checkdocs (>=2.4)", "pytest-flake8", "pytest-cov", "pytest-enabler (>=1.3)", "packaging", "pyfakefs", "flufl.flake8", "pytest-perf (>=0.9.2)", "pytest-black (>=0.3.7)", "pytest-mypy (>=0.9.1)", "importlib-resources (>=1.3)"]
[[package]]
name = "iniconfig"
version = "1.1.1"
@ -193,6 +294,20 @@ requirements_deprecated_finder = ["pipreqs", "pip-api"]
colors = ["colorama (>=0.4.3,<0.5.0)"]
plugins = ["setuptools"]
[[package]]
name = "jinja2"
version = "3.1.2"
description = "A very fast and expressive template engine."
category = "dev"
optional = false
python-versions = ">=3.7"
[package.dependencies]
MarkupSafe = ">=2.0"
[package.extras]
i18n = ["Babel (>=2.7)"]
[[package]]
name = "lazy-object-proxy"
version = "1.7.1"
@ -201,6 +316,61 @@ category = "dev"
optional = false
python-versions = ">=3.6"
[[package]]
name = "livereload"
version = "2.6.3"
description = "Python LiveReload is an awesome tool for web developers"
category = "dev"
optional = false
python-versions = "*"
[package.dependencies]
six = "*"
tornado = {version = "*", markers = "python_version > \"2.7\""}
[[package]]
name = "lxml"
version = "4.9.1"
description = "Powerful and Pythonic XML processing library combining libxml2/libxslt with the ElementTree API."
category = "dev"
optional = false
python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, != 3.4.*"
[package.extras]
cssselect = ["cssselect (>=0.7)"]
html5 = ["html5lib"]
htmlsoup = ["beautifulsoup4"]
source = ["Cython (>=0.29.7)"]
[[package]]
name = "markdown-it-py"
version = "2.1.0"
description = "Python port of markdown-it. Markdown parsing, done right!"
category = "dev"
optional = false
python-versions = ">=3.7"
[package.dependencies]
mdurl = ">=0.1,<1.0"
[package.extras]
testing = ["pytest-regressions", "pytest-cov", "pytest", "coverage"]
rtd = ["sphinx-book-theme", "sphinx-design", "sphinx-copybutton", "sphinx", "pyyaml", "myst-parser", "attrs"]
profiling = ["gprof2dot"]
plugins = ["mdit-py-plugins"]
linkify = ["linkify-it-py (>=1.0,<2.0)"]
compare = ["panflute (>=2.1.3,<2.2.0)", "mistune (>=2.0.2,<2.1.0)", "mistletoe (>=0.8.1,<0.9.0)", "markdown (>=3.3.6,<3.4.0)", "commonmark (>=0.9.1,<0.10.0)"]
code_style = ["pre-commit (==2.6)"]
benchmarking = ["pytest-benchmark (>=3.2,<4.0)", "pytest", "psutil"]
[[package]]
name = "markupsafe"
version = "2.1.1"
description = "Safely add untrusted strings to HTML/XML markup."
category = "dev"
optional = false
python-versions = ">=3.7"
[[package]]
name = "mccabe"
version = "0.7.0"
@ -209,6 +379,30 @@ category = "dev"
optional = false
python-versions = ">=3.6"
[[package]]
name = "mdit-py-plugins"
version = "0.3.0"
description = "Collection of plugins for markdown-it-py"
category = "dev"
optional = false
python-versions = "~=3.6"
[package.dependencies]
markdown-it-py = ">=1.0.0,<3.0.0"
[package.extras]
testing = ["pytest-regressions", "pytest-cov", "pytest (>=3.6,<4)", "coverage"]
rtd = ["sphinx-book-theme (>=0.1.0,<0.2.0)", "myst-parser (>=0.14.0,<0.15.0)"]
code_style = ["pre-commit (==2.6)"]
[[package]]
name = "mdurl"
version = "0.1.2"
description = "Markdown URL utilities"
category = "dev"
optional = false
python-versions = ">=3.7"
[[package]]
name = "mypy"
version = "0.971"
@ -235,6 +429,29 @@ category = "dev"
optional = false
python-versions = "*"
[[package]]
name = "myst-parser"
version = "0.18.0"
description = "An extended commonmark compliant parser, with bridges to docutils & sphinx."
category = "dev"
optional = false
python-versions = ">=3.7"
[package.dependencies]
docutils = ">=0.15,<0.19"
jinja2 = "*"
markdown-it-py = ">=1.0.0,<3.0.0"
mdit-py-plugins = ">=0.3.0,<0.4.0"
pyyaml = "*"
sphinx = ">=4,<6"
typing-extensions = "*"
[package.extras]
code_style = ["pre-commit (>=2.12,<3.0)"]
linkify = ["linkify-it-py (>=1.0,<2.0)"]
rtd = ["ipython", "sphinx-book-theme", "sphinx-design", "sphinxext-rediraffe (>=0.2.7,<0.3.0)", "sphinxcontrib.mermaid (>=0.7.1,<0.8.0)", "sphinxext-opengraph (>=0.6.3,<0.7.0)"]
testing = ["beautifulsoup4", "coverage", "pytest (>=6,<7)", "pytest-cov", "pytest-regressions", "pytest-param-files (>=0.3.4,<0.4.0)", "sphinx-pytest"]
[[package]]
name = "packaging"
version = "21.3"
@ -494,6 +711,29 @@ pylint = ">=2.3.0"
pytest = ">=5.4"
toml = ">=0.7.1"
[[package]]
name = "python-slugify"
version = "6.1.2"
description = "A Python slugify application that also handles Unicode"
category = "dev"
optional = false
python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*"
[package.dependencies]
text-unidecode = ">=1.3"
Unidecode = {version = ">=1.1.1", optional = true, markers = "extra == \"unidecode\""}
[package.extras]
unidecode = ["Unidecode (>=1.1.1)"]
[[package]]
name = "pytz"
version = "2022.2.1"
description = "World timezone definitions, modern and historical"
category = "dev"
optional = false
python-versions = "*"
[[package]]
name = "pyyaml"
version = "6.0"
@ -502,6 +742,24 @@ category = "dev"
optional = false
python-versions = ">=3.6"
[[package]]
name = "requests"
version = "2.28.1"
description = "Python HTTP for Humans."
category = "dev"
optional = false
python-versions = ">=3.7, <4"
[package.dependencies]
certifi = ">=2017.4.17"
charset-normalizer = ">=2,<3"
idna = ">=2.5,<4"
urllib3 = ">=1.21.1,<1.27"
[package.extras]
socks = ["PySocks (>=1.5.6,!=1.5.7)"]
use_chardet_on_py3 = ["chardet (>=3.0.2,<6)"]
[[package]]
name = "rich"
version = "12.5.1"
@ -534,6 +792,158 @@ category = "dev"
optional = false
python-versions = ">=3.6"
[[package]]
name = "snowballstemmer"
version = "2.2.0"
description = "This package provides 29 stemmers for 28 languages generated from Snowball algorithms."
category = "dev"
optional = false
python-versions = "*"
[[package]]
name = "soupsieve"
version = "2.3.2.post1"
description = "A modern CSS selector implementation for Beautiful Soup."
category = "dev"
optional = false
python-versions = ">=3.6"
[[package]]
name = "sphinx"
version = "5.1.1"
description = "Python documentation generator"
category = "dev"
optional = false
python-versions = ">=3.6"
[package.dependencies]
alabaster = ">=0.7,<0.8"
babel = ">=1.3"
colorama = {version = ">=0.3.5", markers = "sys_platform == \"win32\""}
docutils = ">=0.14,<0.20"
imagesize = "*"
importlib-metadata = {version = ">=4.4", markers = "python_version < \"3.10\""}
Jinja2 = ">=2.3"
packaging = "*"
Pygments = ">=2.0"
requests = ">=2.5.0"
snowballstemmer = ">=1.1"
sphinxcontrib-applehelp = "*"
sphinxcontrib-devhelp = "*"
sphinxcontrib-htmlhelp = ">=2.0.0"
sphinxcontrib-jsmath = "*"
sphinxcontrib-qthelp = "*"
sphinxcontrib-serializinghtml = ">=1.1.5"
[package.extras]
docs = ["sphinxcontrib-websupport"]
lint = ["flake8 (>=3.5.0)", "flake8-comprehensions", "flake8-bugbear", "isort", "mypy (>=0.971)", "sphinx-lint", "docutils-stubs", "types-typed-ast", "types-requests"]
test = ["pytest (>=4.6)", "html5lib", "cython", "typed-ast"]
[[package]]
name = "sphinx-autodoc-typehints"
version = "1.19.2"
description = "Type hints (PEP 484) support for the Sphinx autodoc extension"
category = "dev"
optional = false
python-versions = ">=3.7"
[package.dependencies]
Sphinx = ">=5.1.1"
[package.extras]
testing = ["covdefaults (>=2.2)", "coverage (>=6.4.2)", "diff-cover (>=6.5.1)", "nptyping (>=2.2)", "pytest (>=7.1.2)", "pytest-cov (>=3)", "sphobjinv (>=2.2.2)", "typing-extensions (>=4.3)"]
type_comments = ["typed-ast (>=1.5.4)"]
[[package]]
name = "sphinx-material"
version = "0.0.35"
description = "Material sphinx theme"
category = "dev"
optional = false
python-versions = ">=3.6"
[package.dependencies]
beautifulsoup4 = "*"
css-html-js-minify = "*"
lxml = "*"
python-slugify = {version = "*", extras = ["unidecode"]}
sphinx = ">=2.0"
[package.extras]
dev = ["black (==19.10b0)"]
[[package]]
name = "sphinxcontrib-applehelp"
version = "1.0.2"
description = "sphinxcontrib-applehelp is a sphinx extension which outputs Apple help books"
category = "dev"
optional = false
python-versions = ">=3.5"
[package.extras]
test = ["pytest"]
lint = ["docutils-stubs", "mypy", "flake8"]
[[package]]
name = "sphinxcontrib-devhelp"
version = "1.0.2"
description = "sphinxcontrib-devhelp is a sphinx extension which outputs Devhelp document."
category = "dev"
optional = false
python-versions = ">=3.5"
[package.extras]
test = ["pytest"]
lint = ["docutils-stubs", "mypy", "flake8"]
[[package]]
name = "sphinxcontrib-htmlhelp"
version = "2.0.0"
description = "sphinxcontrib-htmlhelp is a sphinx extension which renders HTML help files"
category = "dev"
optional = false
python-versions = ">=3.6"
[package.extras]
test = ["html5lib", "pytest"]
lint = ["docutils-stubs", "mypy", "flake8"]
[[package]]
name = "sphinxcontrib-jsmath"
version = "1.0.1"
description = "A sphinx extension which renders display math in HTML via JavaScript"
category = "dev"
optional = false
python-versions = ">=3.5"
[package.extras]
test = ["mypy", "flake8", "pytest"]
[[package]]
name = "sphinxcontrib-qthelp"
version = "1.0.3"
description = "sphinxcontrib-qthelp is a sphinx extension which outputs QtHelp document."
category = "dev"
optional = false
python-versions = ">=3.5"
[package.extras]
test = ["pytest"]
lint = ["docutils-stubs", "mypy", "flake8"]
[[package]]
name = "sphinxcontrib-serializinghtml"
version = "1.1.5"
description = "sphinxcontrib-serializinghtml is a sphinx extension which outputs \"serialized\" HTML files (json and pickle)."
category = "dev"
optional = false
python-versions = ">=3.5"
[package.extras]
test = ["pytest"]
lint = ["docutils-stubs", "mypy", "flake8"]
[[package]]
name = "stevedore"
version = "4.0.0"
@ -545,6 +955,14 @@ python-versions = ">=3.8"
[package.dependencies]
pbr = ">=2.0.0,<2.1.0 || >2.1.0"
[[package]]
name = "text-unidecode"
version = "1.3"
description = "The most basic Text::Unidecode port"
category = "dev"
optional = false
python-versions = "*"
[[package]]
name = "toml"
version = "0.10.2"
@ -569,6 +987,14 @@ category = "dev"
optional = false
python-versions = ">=3.6,<4.0"
[[package]]
name = "tornado"
version = "6.2"
description = "Tornado is a Python web framework and asynchronous networking library, originally developed at FriendFeed."
category = "dev"
optional = false
python-versions = ">= 3.7"
[[package]]
name = "tox"
version = "3.25.1"
@ -615,6 +1041,27 @@ category = "dev"
optional = false
python-versions = ">=3.7"
[[package]]
name = "unidecode"
version = "1.3.4"
description = "ASCII transliterations of Unicode text"
category = "dev"
optional = false
python-versions = ">=3.5"
[[package]]
name = "urllib3"
version = "1.26.11"
description = "HTTP library with thread-safe connection pooling, file post, and more."
category = "dev"
optional = false
python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*, <4"
[package.extras]
brotli = ["brotlicffi (>=0.8.0)", "brotli (>=1.0.9)", "brotlipy (>=0.6.0)"]
secure = ["pyOpenSSL (>=0.14)", "cryptography (>=1.3.4)", "idna (>=2.0.0)", "certifi", "ipaddress"]
socks = ["PySocks (>=1.5.6,!=1.5.7,<2.0)"]
[[package]]
name = "virtualenv"
version = "20.16.3"
@ -640,17 +1087,37 @@ category = "dev"
optional = false
python-versions = "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,>=2.7"
[[package]]
name = "zipp"
version = "3.8.1"
description = "Backport of pathlib-compatible object wrapper for zip files"
category = "dev"
optional = false
python-versions = ">=3.7"
[package.extras]
docs = ["sphinx", "jaraco.packaging (>=9)", "rst.linker (>=1.9)", "jaraco.tidelift (>=1.4)"]
testing = ["pytest (>=6)", "pytest-checkdocs (>=2.4)", "pytest-flake8", "pytest-cov", "pytest-enabler (>=1.3)", "jaraco.itertools", "func-timeout", "pytest-black (>=0.3.7)", "pytest-mypy (>=0.9.1)"]
[metadata]
lock-version = "1.1"
python-versions = "^3.8"
content-hash = "e31c3fd874ec8dee26ad41df78f0ee2cb019d47af61879733499b1fff58745bd"
content-hash = "f9cb922e5414af5df593bc60728260a5af55cd7e49a088955c9dcc4c74409217"
[metadata.files]
alabaster = []
astroid = []
atomicwrites = []
attrs = []
babel = []
bandit = []
beautifulsoup4 = []
black = []
certifi = [
{file = "certifi-2022.6.15-py3-none-any.whl", hash = "sha256:fe86415d55e84719d75f8b69414f6438ac3547d2078ab91b67e779ef69378412"},
{file = "certifi-2022.6.15.tar.gz", hash = "sha256:84c85a9078b11105f04f3036a9482ae10e4621616db313fe045dd24743a0820d"},
]
charset-normalizer = []
click = [
{file = "click-8.1.3-py3-none-any.whl", hash = "sha256:bb4d8133cb15a609f44e8213d9b391b0809795062913b383c62be0ee95b1db48"},
{file = "click-8.1.3.tar.gz", hash = "sha256:7682dc8afb30297001674575ea00d1814d808d6a36af415a82bd481d37ba7b8e"},
@ -664,23 +1131,80 @@ commonmark = [
{file = "commonmark-0.9.1.tar.gz", hash = "sha256:452f9dc859be7f06631ddcb328b6919c67984aca654e5fefb3914d54691aed60"},
]
coverage = []
css-html-js-minify = []
dill = []
distlib = []
docutils = []
filelock = []
gitdb = []
gitpython = []
idna = [
{file = "idna-3.3-py3-none-any.whl", hash = "sha256:84d9dd047ffa80596e0f246e2eab0b391788b0503584e8945f2368256d2735ff"},
{file = "idna-3.3.tar.gz", hash = "sha256:9d643ff0a55b762d5cdb124b8eaa99c66322e2157b69160bc32796e824360e6d"},
]
imagesize = []
importlib-metadata = []
iniconfig = [
{file = "iniconfig-1.1.1-py2.py3-none-any.whl", hash = "sha256:011e24c64b7f47f6ebd835bb12a743f2fbe9a26d4cecaa7f53bc4f35ee9da8b3"},
{file = "iniconfig-1.1.1.tar.gz", hash = "sha256:bc3af051d7d14b2ee5ef9969666def0cd1a000e121eaea580d4a313df4b37f32"},
]
isort = []
jinja2 = []
lazy-object-proxy = []
livereload = []
lxml = []
markdown-it-py = []
markupsafe = [
{file = "MarkupSafe-2.1.1-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:86b1f75c4e7c2ac2ccdaec2b9022845dbb81880ca318bb7a0a01fbf7813e3812"},
{file = "MarkupSafe-2.1.1-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:f121a1420d4e173a5d96e47e9a0c0dcff965afdf1626d28de1460815f7c4ee7a"},
{file = "MarkupSafe-2.1.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a49907dd8420c5685cfa064a1335b6754b74541bbb3706c259c02ed65b644b3e"},
{file = "MarkupSafe-2.1.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:10c1bfff05d95783da83491be968e8fe789263689c02724e0c691933c52994f5"},
{file = "MarkupSafe-2.1.1-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:b7bd98b796e2b6553da7225aeb61f447f80a1ca64f41d83612e6139ca5213aa4"},
{file = "MarkupSafe-2.1.1-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:b09bf97215625a311f669476f44b8b318b075847b49316d3e28c08e41a7a573f"},
{file = "MarkupSafe-2.1.1-cp310-cp310-musllinux_1_1_i686.whl", hash = "sha256:694deca8d702d5db21ec83983ce0bb4b26a578e71fbdbd4fdcd387daa90e4d5e"},
{file = "MarkupSafe-2.1.1-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:efc1913fd2ca4f334418481c7e595c00aad186563bbc1ec76067848c7ca0a933"},
{file = "MarkupSafe-2.1.1-cp310-cp310-win32.whl", hash = "sha256:4a33dea2b688b3190ee12bd7cfa29d39c9ed176bda40bfa11099a3ce5d3a7ac6"},
{file = "MarkupSafe-2.1.1-cp310-cp310-win_amd64.whl", hash = "sha256:dda30ba7e87fbbb7eab1ec9f58678558fd9a6b8b853530e176eabd064da81417"},
{file = "MarkupSafe-2.1.1-cp37-cp37m-macosx_10_9_x86_64.whl", hash = "sha256:671cd1187ed5e62818414afe79ed29da836dde67166a9fac6d435873c44fdd02"},
{file = "MarkupSafe-2.1.1-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:3799351e2336dc91ea70b034983ee71cf2f9533cdff7c14c90ea126bfd95d65a"},
{file = "MarkupSafe-2.1.1-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:e72591e9ecd94d7feb70c1cbd7be7b3ebea3f548870aa91e2732960fa4d57a37"},
{file = "MarkupSafe-2.1.1-cp37-cp37m-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:6fbf47b5d3728c6aea2abb0589b5d30459e369baa772e0f37a0320185e87c980"},
{file = "MarkupSafe-2.1.1-cp37-cp37m-musllinux_1_1_aarch64.whl", hash = "sha256:d5ee4f386140395a2c818d149221149c54849dfcfcb9f1debfe07a8b8bd63f9a"},
{file = "MarkupSafe-2.1.1-cp37-cp37m-musllinux_1_1_i686.whl", hash = "sha256:bcb3ed405ed3222f9904899563d6fc492ff75cce56cba05e32eff40e6acbeaa3"},
{file = "MarkupSafe-2.1.1-cp37-cp37m-musllinux_1_1_x86_64.whl", hash = "sha256:e1c0b87e09fa55a220f058d1d49d3fb8df88fbfab58558f1198e08c1e1de842a"},
{file = "MarkupSafe-2.1.1-cp37-cp37m-win32.whl", hash = "sha256:8dc1c72a69aa7e082593c4a203dcf94ddb74bb5c8a731e4e1eb68d031e8498ff"},
{file = "MarkupSafe-2.1.1-cp37-cp37m-win_amd64.whl", hash = "sha256:97a68e6ada378df82bc9f16b800ab77cbf4b2fada0081794318520138c088e4a"},
{file = "MarkupSafe-2.1.1-cp38-cp38-macosx_10_9_universal2.whl", hash = "sha256:e8c843bbcda3a2f1e3c2ab25913c80a3c5376cd00c6e8c4a86a89a28c8dc5452"},
{file = "MarkupSafe-2.1.1-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:0212a68688482dc52b2d45013df70d169f542b7394fc744c02a57374a4207003"},
{file = "MarkupSafe-2.1.1-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:8e576a51ad59e4bfaac456023a78f6b5e6e7651dcd383bcc3e18d06f9b55d6d1"},
{file = "MarkupSafe-2.1.1-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:4b9fe39a2ccc108a4accc2676e77da025ce383c108593d65cc909add5c3bd601"},
{file = "MarkupSafe-2.1.1-cp38-cp38-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:96e37a3dc86e80bf81758c152fe66dbf60ed5eca3d26305edf01892257049925"},
{file = "MarkupSafe-2.1.1-cp38-cp38-musllinux_1_1_aarch64.whl", hash = "sha256:6d0072fea50feec76a4c418096652f2c3238eaa014b2f94aeb1d56a66b41403f"},
{file = "MarkupSafe-2.1.1-cp38-cp38-musllinux_1_1_i686.whl", hash = "sha256:089cf3dbf0cd6c100f02945abeb18484bd1ee57a079aefd52cffd17fba910b88"},
{file = "MarkupSafe-2.1.1-cp38-cp38-musllinux_1_1_x86_64.whl", hash = "sha256:6a074d34ee7a5ce3effbc526b7083ec9731bb3cbf921bbe1d3005d4d2bdb3a63"},
{file = "MarkupSafe-2.1.1-cp38-cp38-win32.whl", hash = "sha256:421be9fbf0ffe9ffd7a378aafebbf6f4602d564d34be190fc19a193232fd12b1"},
{file = "MarkupSafe-2.1.1-cp38-cp38-win_amd64.whl", hash = "sha256:fc7b548b17d238737688817ab67deebb30e8073c95749d55538ed473130ec0c7"},
{file = "MarkupSafe-2.1.1-cp39-cp39-macosx_10_9_universal2.whl", hash = "sha256:e04e26803c9c3851c931eac40c695602c6295b8d432cbe78609649ad9bd2da8a"},
{file = "MarkupSafe-2.1.1-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:b87db4360013327109564f0e591bd2a3b318547bcef31b468a92ee504d07ae4f"},
{file = "MarkupSafe-2.1.1-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:99a2a507ed3ac881b975a2976d59f38c19386d128e7a9a18b7df6fff1fd4c1d6"},
{file = "MarkupSafe-2.1.1-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:56442863ed2b06d19c37f94d999035e15ee982988920e12a5b4ba29b62ad1f77"},
{file = "MarkupSafe-2.1.1-cp39-cp39-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:3ce11ee3f23f79dbd06fb3d63e2f6af7b12db1d46932fe7bd8afa259a5996603"},
{file = "MarkupSafe-2.1.1-cp39-cp39-musllinux_1_1_aarch64.whl", hash = "sha256:33b74d289bd2f5e527beadcaa3f401e0df0a89927c1559c8566c066fa4248ab7"},
{file = "MarkupSafe-2.1.1-cp39-cp39-musllinux_1_1_i686.whl", hash = "sha256:43093fb83d8343aac0b1baa75516da6092f58f41200907ef92448ecab8825135"},
{file = "MarkupSafe-2.1.1-cp39-cp39-musllinux_1_1_x86_64.whl", hash = "sha256:8e3dcf21f367459434c18e71b2a9532d96547aef8a871872a5bd69a715c15f96"},
{file = "MarkupSafe-2.1.1-cp39-cp39-win32.whl", hash = "sha256:d4306c36ca495956b6d568d276ac11fdd9c30a36f1b6eb928070dc5360b22e1c"},
{file = "MarkupSafe-2.1.1-cp39-cp39-win_amd64.whl", hash = "sha256:46d00d6cfecdde84d40e572d63735ef81423ad31184100411e6e3388d405e247"},
{file = "MarkupSafe-2.1.1.tar.gz", hash = "sha256:7f91197cc9e48f989d12e4e6fbc46495c446636dfc81b9ccf50bb0ec74b91d4b"},
]
mccabe = []
mdit-py-plugins = []
mdurl = []
mypy = []
mypy-extensions = [
{file = "mypy_extensions-0.4.3-py2.py3-none-any.whl", hash = "sha256:090fedd75945a69ae91ce1303b5824f428daf5a028d2f6ab8a299250a846f15d"},
{file = "mypy_extensions-0.4.3.tar.gz", hash = "sha256:2d82818f5bb3e369420cb3c4060a7970edba416647068eb4c5343488a6c604a8"},
]
myst-parser = []
packaging = [
{file = "packaging-21.3-py3-none-any.whl", hash = "sha256:ef103e05f519cdc783ae24ea4e2e0f508a9c99b2d4969652eed6a2e1ea5bd522"},
{file = "packaging-21.3.tar.gz", hash = "sha256:dd47c42927d89ab911e606518907cc2d3a1f38bbd026385970643f9c5b8ecfeb"},
@ -724,22 +1248,44 @@ pytest-mock = []
pytest-mypy = []
pytest-order = []
pytest-pylint = []
python-slugify = []
pytz = []
pyyaml = []
requests = []
rich = []
six = [
{file = "six-1.16.0-py2.py3-none-any.whl", hash = "sha256:8abb2f1d86890a2dfb989f9a77cfcfd3e47c2a354b01111771326f8aa26e0254"},
{file = "six-1.16.0.tar.gz", hash = "sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926"},
]
smmap = []
snowballstemmer = []
soupsieve = []
sphinx = []
sphinx-autodoc-typehints = []
sphinx-material = []
sphinxcontrib-applehelp = []
sphinxcontrib-devhelp = []
sphinxcontrib-htmlhelp = []
sphinxcontrib-jsmath = []
sphinxcontrib-qthelp = []
sphinxcontrib-serializinghtml = []
stevedore = []
text-unidecode = []
toml = []
tomli = [
{file = "tomli-2.0.1-py3-none-any.whl", hash = "sha256:939de3e7a6161af0c887ef91b7d41a53e7c5a1ca976325f429cb46ea9bc30ecc"},
{file = "tomli-2.0.1.tar.gz", hash = "sha256:de526c12914f0c550d15924c62d72abc48d6fe7364aa87328337a31007fe8a4f"},
]
tomlkit = []
tornado = []
tox = []
tox-poetry = []
typing-extensions = []
unidecode = [
{file = "Unidecode-1.3.4-py3-none-any.whl", hash = "sha256:afa04efcdd818a93237574791be9b2817d7077c25a068b00f8cff7baa4e59257"},
{file = "Unidecode-1.3.4.tar.gz", hash = "sha256:8e4352fb93d5a735c788110d2e7ac8e8031eb06ccbfe8d324ab71735015f9342"},
]
urllib3 = []
virtualenv = []
wrapt = []
zipp = []

View File

@ -1,6 +1,6 @@
[tool.poetry]
name = "pytest-csv-params"
version = "0.3.4"
version = "0.4.0"
description = "Pytest plugin for Test Case Parametrization with CSV files"
authors = ["Juergen Edelbluth <csv_params@jued.de>"]
license = "MIT"
@ -35,7 +35,8 @@ packages = [
"Issue Tracker" = "https://git.codebau.dev/pytest-plugins/pytest-csv-params/issues"
"Wiki" = "https://git.codebau.dev/pytest-plugins/pytest-csv-params/wiki"
"Releases" = "https://git.codebau.dev/pytest-plugins/pytest-csv-params/releases"
"Documentation" = "https://git.codebau.dev/pytest-plugins/pytest-csv-params/src/branch/main/README.md"
"Documentation" = "https://docs.codebau.dev/pytest-plugins/pytest-csv-params/"
"Changelog" = "https://docs.codebau.dev/pytest-plugins/pytest-csv-params/pages/changelog.html"
[tool.poetry.plugins."pytest11"]
"pytest-csv-params" = "pytest_csv_params.plugin"
@ -82,6 +83,9 @@ omit = [
"*/test_plugin_test_error.py",
"*/test_base_dir_param.py",
"*/test_plugin_test_text_shorthand.py",
"*/test_plugin_test_all_one.py",
"*/test_plugin_test_all_two.py",
"*/test_plugin_test_all_three.py",
]
relative_files = true
@ -141,6 +145,12 @@ pytest-clarity = "^1.0.1"
pytest-bandit = "^0.6.1"
pytest-mypy = "^0.9.1"
pytest-order = "^1.0.1"
Sphinx = "^5.1.1"
myst-parser = "^0.18.0"
sphinx-material = "^0.0.35"
sphinx-autodoc-typehints = "^1.19.2"
livereload = "^2.6.3"
tomli = "^2.0.1"
[build-system]
requires = ["poetry-core>=1.0.0"]

View File

@ -1,6 +1,11 @@
"""
Add CSV Data to test
This module defines/publishes the main decorator.
"""
from _ptcsvp.parametrize import add_parametrization
csv_params = add_parametrization
"""
Decorator ``@csv_params``
For supported arguments, see :py:meth:`~_ptcsvp.parametrize.add_parametrization`.
"""

View File

@ -1,12 +1,18 @@
"""
CSV Dialects
Definition of CSV dialects (CSV file formats). At the moment, there is only the default dialect
:class:`~pytest_csv_params.dialect.CsvParamsDefaultDialect`.
"""
import csv
class CsvParamsDefaultDialect(csv.Dialect): # pylint: disable=too-few-public-methods
"""
Basic CSV Dialect for most Tests
This is the default dialect (or CSV file format) for parametrizing test. It is used when no other dialect is
defined.
One can easily adapt it to match your own CSV files. Just use this or :class:`csv.Dialect` as base class.
See :class:`csv.Dialect` for configuration reference.
"""
delimiter = ","

View File

@ -1,27 +1,30 @@
"""
Exceptions
Collection of all plugin specific exceptions. All exceptions are derived from very common base types, such as
:class:`FileNotFoundError`, :class:`IOError` or :class:`ValueError` to ease the exception handling.
"""
class CsvParamsDataFileNotFound(FileNotFoundError):
"""
File Not Found
This exception is thrown when a CSV file was not found.
"""
class CsvParamsDataFileInaccessible(IOError):
"""
Cannot Access the File
This exception is thrown when the CSV file is inaccessible.
"""
class CsvParamsDataFileInvalid(ValueError):
"""
CSV Data is somehow invalid
This exception is thrown when a CSV file contains invalid data.
See the exception message for more details.
"""
class CsvHeaderNameInvalid(ValueError):
"""
Invalid Header Name
This exception is thrown when a CSV file contains an invalid header name that could not be replaced.
"""

View File

@ -1,5 +1,7 @@
"""
Pytest Plugin Entrypoint
Pytest Plugin Entrypoint:
This module contains all the code to initialize the pytest plugin. This is the entrypoint configured in the
`pyproject.toml` as `pytest11`.
"""
from _ptcsvp.cmdline import pytest_addoption as _pytest_addoption
@ -13,7 +15,17 @@ check_pytest_version()
# Basic config
pytest_configure = _pytest_configure
"""
Hook in our :meth:`_ptcsvp.configure.pytest_configure` method to setup the plugin setup
"""
pytest_unconfigure = _pytest_unconfigure
"""
Hook in our :meth:`_ptcsvp.configure.pytest_unconfigure` method to setup the plugin teardown
"""
# Command Line Arguments
pytest_addoption = _pytest_addoption
"""
Hook in our :meth:`_ptcsvp.cmdline.pytest_addoption` method to setup our command line arguments
"""

View File

@ -1,19 +1,65 @@
"""
Types to ease the usage of the API
This module contains type definitions to ease the usage of the API and its documentation.
Some types are somewhat complex, and it is easier to use a single word/reference instead of a complex typing construct.
"""
import csv
from typing import Any, Callable, Dict, Optional, Type
DataCast = Callable[[str], Any]
"""
A :class:`DataCast` describes how a data casting callable must be implemented. It requires one parameter of the type
:class:`str` and can return anything that is required.
"""
DataCastDict = Dict[str, DataCast]
"""
A :class:`DataCastDict` describes how a dictionary of data casting callables must look like. The key is a :class:`str`
describing the column name, the value is a :class:`DataCast`.
"""
DataCasts = Optional[DataCastDict]
"""
The :class:`DataCasts` type describes the type of the `data_casts` parameter of the
:meth:`~pytest_csv_params.decorator.csv_params` decorator. An optional :class:`DataCastDict`.
"""
BaseDir = Optional[str]
"""
The :class:`BaseDir` describes the type of the `base_dir` parameter of the
:meth:`~pytest_csv_params.decorator.csv_params` decorator to search for non-absolute CSV files. It is simply an optional
:class:`str`.
"""
IdColName = Optional[str]
"""
The :class:`IdColName` describes the type of the `id_col` parameter of the
:meth:`~pytest_csv_params.decorator.csv_params` decorator to name the ID column from a CSV file. It is simply an
optional :class:`str`.
"""
DataFile = str
"""
The :class:`DataFile` describes the type if the `data_file` parameter of the
:meth:`~pytest_csv_params.decorator.csv_params` decorator to define the CSV file to use. It is an obligatory
:class:`str`.
"""
CsvDialect = Type[csv.Dialect]
"""
The :class:`CsvDialect` describes the type of the `dialect` parameter of the
:meth:`~pytest_csv_params.decorator.csv_params` decorator. It is required, but it has an default value in
:class:`pytest_csv_params.dialect.CsvParamsDefaultDialect`.
"""
HeaderRenamesDict = Dict[str, str]
"""
The :class:`HeaderRenamesDict` describes how a dictionary of header renames must look. Keys and values must both be of
type :class:`str`.
"""
HeaderRenames = Optional[HeaderRenamesDict]
"""
The :class:`HeaderRenames` describes the type of the `header_renames` parameter of the
:meth:`~pytest_csv_params.decorator.csv_params` decorator. It is just an optional :class:`HeaderRenamesDict`.
"""

View File

@ -0,0 +1,9 @@
"Test-ID", "Number of items", "Dimensions of item", "Expected Container Size", "Expect Exception?", "Expected Message"
"Small Container 1", "15", "1 x 2 x 3", "1000", "N", ""
"Small Container 2", "125", "2 x 2 x 2", "1000", "N", ""
"Small Container 3", "16", "3 x 4 x 5", "1000", "N", ""
"Medium Container", "17", "3 x 4 x 5", "2500", "N", ""
"Large Container 1", "2", "15 x 12 x 10", "7500", "N", ""
"Large Container 2", "1", "16 x 20 x 20", "7500", "N", ""
"Not fitting 1", "2", "16 x 20 x 18", "0", "Y", "No container available"
"Not fitting 2", "7501", "1 x 1 x 1", "0", "Y", "No container available"
1 Test-ID Number of items Dimensions of item Expected Container Size Expect Exception? Expected Message
2 Small Container 1 15 1 x 2 x 3 1000 N
3 Small Container 2 125 2 x 2 x 2 1000 N
4 Small Container 3 16 3 x 4 x 5 1000 N
5 Medium Container 17 3 x 4 x 5 2500 N
6 Large Container 1 2 15 x 12 x 10 7500 N
7 Large Container 2 1 16 x 20 x 20 7500 N
8 Not fitting 1 2 16 x 20 x 18 0 Y No container available
9 Not fitting 2 7501 1 x 1 x 1 0 Y No container available

View File

@ -1,5 +1,9 @@
"""
Conftest project global
Project global fixtures, plugins etc.
"""
pytest_plugins = ["pytester"]
"""
Load the fixture `pytester` for all tests. Even if we don't need it everywhere (we need it only during the plugin
tests), this fixture requires to be loaded in the topmost :mod:`~tests.conftest` module.
"""

View File

@ -9,5 +9,5 @@ from pytest_csv_params.decorator import csv_params
"expected_length": int,
}
)
def test_fruits(word, expected_length):
def test_{{test_name}}(word, expected_length):
assert len(word) == expected_length

View File

@ -1,10 +1,10 @@
"""
Configuration for the tests
... and local Plugins
Local configuration and fixture providing for the Plugin tests
"""
import subprocess
from os.path import dirname, join
from typing import Callable, Generator
from typing import Callable, Generator, Union
import pytest
from _pytest.config import Config
@ -12,7 +12,10 @@ from _pytest.config import Config
def get_csv(csv: str) -> str:
"""
Get CSV data
Helper Method: Read CSV file from the tests assets directory under ``tests/plugin/assets``.
:param csv: Name of the CSV file, without the .csv extension
:returns: CSV data as string
"""
with open(join(dirname(__file__), "assets", f"{csv}.csv"), "rb") as csv_fh:
csv_data = csv_fh.read()
@ -22,7 +25,9 @@ def get_csv(csv: str) -> str:
@pytest.fixture(scope="session")
def simple_test_csv() -> str:
"""
Provide simple CSV data
Test fixture: Good simple CSV
:returns: CSV data as string
"""
return get_csv("simple-test")
@ -30,7 +35,9 @@ def simple_test_csv() -> str:
@pytest.fixture(scope="session")
def bad_test_csv() -> str:
"""
Provide bad CSV data
Test fixture: Bad CSV
:returns: Bad CSV data as string
"""
return get_csv("bad-test")
@ -38,25 +45,33 @@ def bad_test_csv() -> str:
@pytest.fixture(scope="session")
def text_test_csv() -> str:
"""
Provide text-only CSV data
Test Fixture: Text-only CSV
:returns: Text-only CSV data as string
"""
return get_csv("text-only")
@pytest.fixture(scope="session")
def simple_fruit_test() -> Callable[[str], str]:
def simple_fruit_test() -> Union[Callable[[str], str], Callable[[str, str], str]]:
"""
Provide simple test case
Test Fixture: Template of a simple test case
:returns: A method where a data file can be filled in and what will return a valid pytest test case that can be
saved to a .py file
"""
with open(join(dirname(__file__), "assets", "fruit_test.tpl"), "rt", encoding="utf-8") as test_fh:
test_data = test_fh.read()
return lambda file: test_data.replace("{{data_file}}", file)
return lambda file, test="fruit": test_data.replace("{{data_file}}", file).replace("{{test_name}}", test)
@pytest.fixture(scope="session")
def simple_text_test() -> Callable[[str], str]:
"""
Provide simple text test case
Test Fixture: Template of a simple text test case
:returns: A method where a data file can be filled in and what will return a valid pytest test case that can be
saved to a .py file
"""
with open(join(dirname(__file__), "assets", "text_test.tpl"), "rt", encoding="utf-8") as test_fh:
test_data = test_fh.read()
@ -66,7 +81,11 @@ def simple_text_test() -> Callable[[str], str]:
@pytest.fixture(scope="session", autouse=True)
def install_plugin_locally(pytestconfig: Config) -> Generator[None, None, None]:
"""
Install the local package
Auto-use Test Fixture to install our plugin in the test environment, so that it can be used with the ``pytester``
fixture. The package is removed after the test session automatically.
:param pytestconfig: Fixture from pytest that contains the test configuration
:returns: An empty generator (from the ``yield``), to let the tests run and cleanup afterwards
"""
root = pytestconfig.rootpath
_ = subprocess.run(["pip", "install", "-e", "."], shell=True, cwd=root, check=True, capture_output=True)

View File

@ -1,6 +1,10 @@
"""
Test the usage of the Command Line
Command line argument handling
==============================
**Module:** ``tests.plugin.test_cmd_line``
"""
from pathlib import Path
from typing import Callable
@ -18,10 +22,18 @@ from _ptcsvp.cmdline import HELP_TEXT
],
)
def test_base_dir_param(
pytester: Pytester, base_dir: bool, simple_test_csv: str, simple_fruit_test: Callable[[str], str]
pytester: Pytester,
base_dir: bool,
simple_test_csv: str,
simple_fruit_test: Callable[[str], str],
) -> None:
"""
Test that the cmd arg is valued
Test if the ``--csv-params-base-dir`` command line argument is valued. For laziness, it uses a poor parametrization.
:param pytester: Pytester fixture
:param base_dir: Shall the base dir parameter be set?
:param simple_test_csv: Fixture :meth:`~tests.plugin.conftest.simple_test_csv`
:param simple_fruit_test: Fixture :meth:`~tests.plugin.conftest.simple_fruit_test`
"""
csv_file = str(pytester.makefile(".csv", simple_test_csv).absolute())
@ -40,7 +52,9 @@ def test_base_dir_param(
def test_help(pytester: Pytester) -> None:
"""
Test if the plugin is in the help
Test that the pytest help now contains our command line argument with our help text.
:param pytester: Pytester fixture
"""
result = pytester.runpytest("--help")

View File

@ -1,6 +1,10 @@
"""
Just try to call our plugin
Plugin Calls
============
**Module:** ``tests.plugin.test_plugin``
"""
from typing import Callable
from _pytest.pytester import Pytester
@ -10,7 +14,11 @@ def test_plugin_test_multiplication(
pytester: Pytester, simple_test_csv: str, simple_fruit_test: Callable[[str], str]
) -> None:
"""
Simple Roundtrip Smoke Test
Test a simple round trip (positive test case)
:param pytester: Pytester fixture
:param simple_test_csv: Fixture :meth:`~tests.plugin.conftest.simple_test_csv`
:param simple_fruit_test: Fixture :meth:`~tests.plugin.conftest.simple_fruit_test`
"""
csv_file = str(pytester.makefile(".csv", simple_test_csv).absolute())
@ -23,7 +31,11 @@ def test_plugin_test_multiplication(
def test_plugin_test_error(pytester: Pytester, bad_test_csv: str, simple_fruit_test: Callable[[str], str]) -> None:
"""
Simple Error Behaviour Test
Test if a test error is correctly recognized
:param pytester: Pytester fixture
:param bad_test_csv: Fixture :meth:`~tests.plugin.conftest.bad_test_csv`
:param simple_fruit_test: Fixture :meth:`~tests.plugin.conftest.simple_fruit_test`
"""
csv_file = str(pytester.makefile(".csv", bad_test_csv).absolute())
@ -38,7 +50,11 @@ def test_plugin_test_text_shorthand(
pytester: Pytester, text_test_csv: str, simple_text_test: Callable[[str], str]
) -> None:
"""
Simple Roundtrip Smoke Test
Test the shorthand version of the plugin's decorator
:param pytester: Pytester fixture
:param text_test_csv: Fixture :meth:`~tests.plugin.conftest.text_test_csv`
:param simple_text_test: Fixture :meth:`~tests.plugin.conftest.simple_text_test`
"""
csv_file = str(pytester.makefile(".csv", text_test_csv).absolute())
@ -47,3 +63,36 @@ def test_plugin_test_text_shorthand(
result = pytester.runpytest("-p", "no:bandit")
result.assert_outcomes(passed=2, failed=1)
def test_plugin_all_tests_at_once( # pylint: disable=too-many-arguments
pytester: Pytester,
text_test_csv: str,
bad_test_csv: str,
simple_test_csv: str,
simple_fruit_test: Callable[[str, str], str],
simple_text_test: Callable[[str], str],
) -> None:
"""
This is a meta test to check if multiple files would work also. Basically, it's a combination of all the other
plugin invocation tests of the module :mod:`tests.plugin.test_plugin`.
We can't run the error-prone test here, because it would stop all tests.
:param pytester: Pytester fixture
:param text_test_csv: Fixture :meth:`~tests.plugin.conftest.text_test_csv`
:param bad_test_csv: Fixture :meth:`~tests.plugin.conftest.bad_test_csv`
:param text_test_csv: Fixture :meth:`~tests.plugin.conftest.text_test_csv`
:param simple_fruit_test: Fixture :meth:`~tests.plugin.conftest.simple_fruit_test`
:param simple_text_test: Fixture :meth:`~tests.plugin.conftest.simple_text_test`
"""
csv_file_text = str(pytester.makefile(".1.csv", text_test_csv).absolute())
pytester.makepyfile(test_plugin_test_all_one=simple_text_test(csv_file_text))
csv_file_bad = str(pytester.makefile(".2.csv", bad_test_csv).absolute())
pytester.makepyfile(test_plugin_test_all_two=simple_fruit_test(csv_file_bad, "bad_one"))
csv_file_good = str(pytester.makefile(".3.csv", simple_test_csv).absolute())
pytester.makepyfile(test_plugin_test_all_three=simple_fruit_test(csv_file_good, "good_one"))
result = pytester.runpytest("-p", "no:bandit", "test_plugin_test_all_one.py", "test_plugin_test_all_three.py")
result.assert_outcomes(passed=5, failed=2, errors=0)

View File

@ -1,5 +1,5 @@
"""
Configuration for the POC tests
Local configuration and fixture providing for POC tests
"""
from typing import Dict, Type
@ -9,7 +9,7 @@ import pytest
class CheapCounter:
"""
A simple counter
A simple cheap counter that is required for counting executions
"""
counter: Dict[str, int] = {}
@ -18,6 +18,9 @@ class CheapCounter:
def get_value(cls, counter: str) -> int:
"""
Get the value of the counter
:param counter: Name of the counter
:returns: Value of the counter
"""
current_value = cls.counter.get(counter, None)
@ -30,6 +33,8 @@ class CheapCounter:
def increment(cls, counter: str) -> None:
"""
Increment the value of the counter
:param counter: Name of the counter to increment
"""
cls.counter[counter] = cls.get_value(counter) + 1
@ -39,6 +44,8 @@ class CheapCounter:
def cheap_counter() -> Type[CheapCounter]:
"""
Deliver a simple counter as fixture
:returns: The Cheap Counter Class
"""
return CheapCounter

View File

@ -1,5 +1,12 @@
"""
Pytest feature: Parametrization
===============================
**Module:** ``tests.poc.test_parametrize_with_generator``
We are using a pytest feature heavily: Parametrization. These tests make sure this feature works still as expected.
Tests in this module run in a predefined order!
"""
from string import ascii_letters
@ -12,7 +19,11 @@ from .conftest import CheapCounter
def data_generator() -> Generator[List[str], None, None]:
"""
Simple Test Data Generator
Helper method: Create Test Data, but keep them as a generator
This helper is used by :meth:`~tests.poc.test_parametrize_with_generator.test_2_generator_parametrize`.
:returns: A bunch of test data as generator
"""
for val_a in ascii_letters[0:5]:
@ -28,9 +39,14 @@ def data_generator() -> Generator[List[str], None, None]:
["c", "d", "c:d"],
],
)
def test_simple_parametrize(val_a: str, val_b: str, val_c: str, cheap_counter: Type[CheapCounter]) -> None:
def test_1_simple_parametrize(val_a: str, val_b: str, val_c: str, cheap_counter: Type[CheapCounter]) -> None:
"""
Test the standard parametrization
Test the simple parametrization from pytest.
:param val_a: Test value A
:param val_b: Test value B
:param val_c: Test value C
:param cheap_counter: Fixture :meth:`~tests.poc.conftest.cheap_counter`
"""
assert f"{val_a}:{val_b}" == val_c
@ -42,9 +58,14 @@ def test_simple_parametrize(val_a: str, val_b: str, val_c: str, cheap_counter: T
["val_a", "val_b", "val_c"],
data_generator(),
)
def test_generator_parametrize(val_a: str, val_b: str, val_c: str, cheap_counter: Type[CheapCounter]) -> None:
def test_2_generator_parametrize(val_a: str, val_b: str, val_c: str, cheap_counter: Type[CheapCounter]) -> None:
"""
Test the generator way
Test the generator parametrization from pytest.
:param val_a: Test value A
:param val_b: Test value B
:param val_c: Test value C
:param cheap_counter: Fixture :meth:`~tests.poc.conftest.cheap_counter`
"""
assert f"{val_a}-{val_b}" == val_c
@ -52,9 +73,11 @@ def test_generator_parametrize(val_a: str, val_b: str, val_c: str, cheap_counter
@pytest.mark.order(3)
def test_evaluation(cheap_counter: Type[CheapCounter]) -> None:
def test_3_evaluation(cheap_counter: Type[CheapCounter]) -> None:
"""
Evaluate the tests before
Evaluate the values of the :meth:`~tests.poc.conftest.cheap_counter` fixture.
:param cheap_counter: Fixture :meth:`~tests.poc.conftest.cheap_counter`
"""
assert cheap_counter.get_value("simple") == 2

View File

@ -1,5 +1,21 @@
"""
This is a test example for a blog post
Example Code for a blog post on juergen.rocks
=============================================
**Module:** ``tests.test_blog_example``
This is a test example for
`a blog post on juergen.rocks <https://juergen.rocks/blog/articles/data-driven-tests-mit-pytest-csv-params.html>`_.
The example consists of serval helper methods and a lot of configuration for the
:meth:`~pytest_csv_params.decorator.csv_params` decorator.
The CSV file looks like this:
.. literalinclude:: ../../../tests/assets/blog-example.csv
:language: text
You find the CSV file in ``tests/assets/blog-example.csv``.
"""
import re
from os.path import dirname, join
@ -9,7 +25,13 @@ from pytest_csv_params.decorator import csv_params
def get_volume(size_data: str) -> int:
"""
Get the volume from size data, return it as mm³
Get the volume from size data, return it as mm³.
Helper method, will be used as a data caster.
:param size_data: String from the CSV file.
:returns: Volume in mm³
:raises: ValueError: When the test data cannot be converted
"""
matcher = re.compile(r"^\D*(?P<l>\d+)\D+(?P<d>\d+)\D+(?P<h>\d+)\D+$").match(size_data)
if matcher is None:
@ -19,7 +41,13 @@ def get_volume(size_data: str) -> int:
def get_container_volume(container_size: str) -> int:
"""
Get the container size (remove the unit, as mm³)
Get the container size (remove the unit, as mm³).
Helper method, will be used as a data caster.
:param container_size: String from the CSV file.
:returns: Volume of the container in mm³
:raises: ValueError: When the test data cannot be converted
"""
matcher = re.compile(r"^\D*(?P<size>\d+)\D+$").match(container_size)
@ -50,7 +78,14 @@ def test_does_it_fit(
anz_schrauben: int, vol_schrauben: int, anz_scheiben: int, vol_scheiben: int, vol_container: int
) -> None:
"""
Simple test to see if all fits in an container
A test example that tries to figure out if all the Schrauben and Scheiben fit in the container, and if the smallest
possible container is chosen.
:param anz_schrauben: Number of Schraubenpäckchen
:param vol_schrauben: Volume (mm³) of a single Schraubenpäckchen
:param anz_scheiben: Number of Scheibenpäckchen
:param vol_scheiben: Volume (mm³) of a single Scheibenpäckchen
:param vol_container: Volume (mm³) of the selected container
"""
available_container_sizes = map(lambda x: x * 1_000_000_000, [1, 5, 10])

View File

@ -1,6 +1,10 @@
"""
Test cleaning the headers
Test for header cleaning
========================
**Module:** ``tests.test_clean_headers``
"""
from typing import List, Optional, Type
import pytest
@ -65,7 +69,15 @@ def test_header_cleaning(
expect_result: List[str],
) -> None:
"""
Test Header Cleaning
This test case tests mainly the :meth:`_ptcsvp.parametrize.clean_headers` method.
There are many single test cases built with parametrization.
:param current_headers: List of headers before cleaning
:param replacing: A replacement dictionary
:param expect_exception: Exception to expect during method call
:param expect_message: Exception message to be expected
:param expect_result: Expected cleaned headers
"""
if expect_exception is not None:
with pytest.raises(expect_exception) as raised_error:

View File

@ -1,6 +1,21 @@
"""
Example Test Case from the documentation
Example Code for a test case for the `README.md` documentation
==============================================================
**Module:** ``tests.test_complex_example``
This module contains a quite simple, yet complex configured test to show what's possible with the plugin.
The example uses this CSV data, as found under ``tests/assets/example.csv``:
.. literalinclude:: ../../../tests/assets/example.csv
:language: text
The test idea here is much the same as the :mod:`tests.test_blog_example` test case.
Why is such a test case here? That's simple: To make sure, the code samples in the documentation still work as designed.
"""
from math import ceil
from os.path import dirname, join
@ -31,6 +46,12 @@ def test_container_size_is_big_enough(
) -> None:
"""
This is just an example test case for the documentation.
:param bananas_shipped: How many mananas were shipped?
:param banana_weight: What's the weight of one banana?
:param apples_shipped: How many apples where shipped?
:param apple_weight: What's the weight of one apple?
:param container_size: How large was the container?
"""
gross_weight = (banana_weight * bananas_shipped) + (apple_weight * apples_shipped)

View File

@ -0,0 +1,97 @@
"""
Example Code for a test case for the documentation site
=======================================================
**Module:** ``tests.test_docs_example``
This is the test code for the documentation site's :doc:`User guide </pages/guide>`. It contains everything that's
needed to follow the example -- and makes sure the code example is working.
"""
from functools import reduce
from os.path import dirname, join
from typing import List, Tuple, Union
import pytest
from pytest_csv_params.decorator import csv_params
def get_smallest_possible_container(
number_of_items: int,
dimensions_of_item: Tuple[int, int, int],
available_container_sizes: Union[List[int], Tuple[int, ...]] = (1000, 2500, 7500),
) -> int:
"""
This is the method to be tested. It searches for the smallest possible container after calculating the volume of the
things to be loaded into the container. A container can only contain items of one product, so it is enough to know
about the size of a single product, and how many of them need to be stored in a container.
The method raises a :class:`ValueError` when the items do not fit any container.
:param number_of_items: Number of items to be packed
:param dimensions_of_item: Edge lengths of a single item
:param available_container_sizes: What container sizes are available? This parameter has a default value
``(1000, 2500, 7500)``.
:raises ValueError: When no matching container can be found
"""
volume = reduce(lambda x, y: x * y, [*dimensions_of_item, number_of_items])
possible_containers = list(filter(lambda s: s >= volume, available_container_sizes))
if len(possible_containers) == 0:
raise ValueError("No container available") from None
return min(possible_containers)
def get_dimensions(dimensions_str: str) -> Tuple[int, int, int]:
"""
Read the dimensions from a string. A helper method to build the dimensions tuple.
:param dimensions_str: The dimensions from the CSV file
:raises ValueError: When the dimensions cannot be converted
:returns: The dimensions as int tuple
"""
dimensions_tuple = tuple(map(lambda x: int(x.strip()), dimensions_str.split("x")))
if len(dimensions_tuple) != 3:
raise ValueError("Dimensions invalid") from None
return dimensions_tuple # type: ignore
@csv_params(
data_file=join(dirname(__file__), "assets", "doc-example.csv"),
id_col="Test-ID",
header_renames={
"Number of items": "number_of_items",
"Dimensions of item": "dimensions_of_item",
"Expected Container Size": "expected_container_size",
"Expect Exception?": "expect_exception",
"Expected Message": "expected_message",
},
data_casts={
"number_of_items": int,
"dimensions_of_item": get_dimensions,
"expected_container_size": int,
"expect_exception": lambda x: x == "Y",
},
)
def test_get_smallest_possible_container(
number_of_items: int,
dimensions_of_item: Tuple[int, int, int],
expected_container_size: int,
expect_exception: bool,
expected_message: str,
) -> None:
"""
This is the test method for the documentation.
:param number_of_items: The number of items
:param dimensions_of_item: The dimensions of a single item
:param expected_container_size: Expected container size
:param expect_exception: Expect a :class:`ValueError`
:param expected_message: Message of the exception
"""
if expect_exception:
with pytest.raises(ValueError) as expected_exception:
get_smallest_possible_container(number_of_items, dimensions_of_item)
assert expected_exception.value.args[0] == expected_message
else:
container_size = get_smallest_possible_container(number_of_items, dimensions_of_item)
assert container_size == expected_container_size

View File

@ -1,6 +1,10 @@
"""
Test the Parametrization Feature
Test for the internal parametrization feature
=============================================
**Module:** ``tests.test_parametrize``
"""
from os.path import dirname, join
from typing import List, Optional, Tuple, Type
@ -86,7 +90,17 @@ def test_parametrization( # pylint: disable=too-many-arguments
expect_message: Optional[str],
) -> None:
"""
Test the parametrization method
This test case tests mainly the internal :meth:`_ptcsvp.parametrize.add_parametrization` method, which is the
backbone of the public :meth:`~pytest_csv_params.decorator.csv_params` decorator.
The test is heavily parametrized. See source code for detail.
:param csv_file: CSV file for the test
:param id_col: The ID column name of the CSV file
:param result: Expected result, as it would be handed over to the :meth:`pytest.mark.parametrize` mark decorator
:param ids: Expected test case IDs
:param expect_exception: Expected exception during call
:param expect_message: Expected exception message during call
"""
data_file = join(dirname(__file__), "assets", f"{csv_file}.csv")
if expect_exception:

View File

@ -1,6 +1,10 @@
"""
Test the reading of the CSV
Test the reading of CSV files
=============================
**Module:** ``tests.test_read_csv``
"""
from os.path import dirname, join
from typing import Optional, Type
@ -42,7 +46,14 @@ def test_csv_reader(
expect_message: Optional[str],
) -> None:
"""
Test behaviour of the CSV loading
This test case tests several CSV reading scenarios (by parametrization). CSV test files are in the ``tests/assets``
folder. The tests target the :meth:`_ptcsvp.parametrize.read_csv` method.
:param csv_file: The file to test with
:param base_dir: The base dir to load the :attr:`csv_file` from
:param expect_lines: Expected read lines from the CSV file
:param expect_exception: Expected exception when running the method
:param expect_message: Expected exception message when running the method
"""
if expect_exception is not None:

View File

@ -1,6 +1,14 @@
"""
Test the varname handling
Test the header name handling
=============================
**Module:** ``tests.test_varname``
The tests in this module aim at testing the validation and cleaning of header/column names of CSV files. Those names
serve as arguments to test methods, and must therefore be valid and not shadow builtin names. Reserved names are checked
also.
"""
import sys
from typing import Optional
@ -42,7 +50,11 @@ from pytest_csv_params.exception import CsvHeaderNameInvalid
)
def test_is_valid_name(var_name: str, is_valid: bool) -> None:
"""
Test if the varname is considered valid or not
This test case checks that the method :meth:`_ptcsvp.varname.is_valid_name` gives the right results. The test method
is parametrized.
:param var_name: The name to check
:param is_valid: Expectation if this is a valid name
"""
assert is_valid_name(var_name) == is_valid
@ -68,7 +80,12 @@ def test_is_valid_name(var_name: str, is_valid: bool) -> None:
)
def test_make_name_valid(var_name: str, valid_var_name: Optional[str], raises_error: bool) -> None:
"""
Check if an invalid name goes valid
This test case checks the method :meth:`_ptcsvp.varname.make_name_valid` builds valid names or throws matching
exceptions if not possible. Therefore, it is parametrized.
:param var_name: The variable name to try to make valid
:param valid_var_name: The name as expected after made valid
:param raises_error: Expect an error?
"""
if raises_error:
@ -91,7 +108,12 @@ def test_make_name_valid(var_name: str, valid_var_name: Optional[str], raises_er
)
def test_310_names(name: str) -> None:
"""
Check if special 3.10 names are considered invalid, when on 3.10
There are a few names that are not valid when using python 3.10 and above. This parametrized test checks if they are
marked as invalid by the method :meth:`_ptcsvp.varname.is_valid_name`.
This test will be skipped on python versions below 3.10.
:param name: An invalid name since python 3.10.
"""
assert not is_valid_name(name)

View File

@ -1,6 +1,12 @@
"""
We are checking the python version for the plugin.
Test the checks for required versions
=====================================
**Module:** ``tests.test_version_checks``
Checking the versions this plugin depends on is crucial for the correct function.
"""
import sys
from typing import List, Optional, Tuple, Type, Union
@ -13,7 +19,11 @@ from _ptcsvp.version import check_pytest_version, check_python_version
def build_version(p_version: str) -> Tuple[Union[int, str], ...]:
"""
Build a Version
Test helper method: Build a version Tuple of a given version string. It is used by the
:meth:`~tests.test_version_check.test_python_version` test case.
:param p_version: Version string
:returns: The version as tuple
"""
elements: List[Union[int, str]] = []
for v_part in p_version.split("."):
@ -64,7 +74,14 @@ def test_python_version(
mocker: MockerFixture, p_version: str, expect_error: Optional[Tuple[Type[Exception], str]]
) -> None:
"""
Test python versions
Test if the python version is correctly recognized and if old versions raise an exception. This tests mainly the
:meth:`_ptcsvp.version.check_python_version` method and is parametrized with a lot of different version combos.
This test uses mocking, and the :meth:`~tests.test_version_check.build_version` helper method.
:param mocker: Mocking fixture
:param p_version: Version string
:param expect_error: Expected error for the given version
"""
mocker.patch.object(sys, "version_info", build_version(p_version))
if expect_error is not None:
@ -112,7 +129,15 @@ def test_pytest_version(
mocker: MockerFixture, p_version: str, expect_error: Optional[Tuple[Type[Exception], str]]
) -> None:
"""
Test pytest versions
Test if the pytest version is correctly recognized and if a too old version raises an exception. This test focuses
on the :meth:`_ptcsvp.version.check_pytest_version` method and is parametrized with a lot of different version
strings.
This test uses mocking.
:param mocker: Mocking fixture
:param p_version: Version string
:param expect_error: Expected error and error message
"""
mocker.patch.object(pytest, "__version__", p_version)
assert pytest.__version__ == p_version