# pytest-csv-params
A pytest plugin to parametrize data-driven tests by CSV files.
[](https://git.codebau.dev/pytest-plugins/pytest-csv-params)
[](https://pypi.org/project/pytest-csv-params/)
[](https://pypi.org/project/pytest-csv-params/)
[](https://pypi.org/project/pytest-csv-params/)
[](https://pypi.org/project/pytest-csv-params/)
## Requirements
- Python 3.8, 3.9, 3.10, 3.11
- pytest >= 7.4
There's no operating system dependent code in this plugin, so it should run anywhere where pytest runs.
## Installation
Simply install it with pip...
```bash
pip install pytest-csv-params
```
... or poetry ...
```bash
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 |
|-------------------------|---------------|----------------------------------------------------------------------|----------------------------------------------|
| `--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` |
## Usage: Decorator
Simply decorate your test method with `@csv_params` (`pytest_csv_params.decorator.csv_params`) and the following parameters:
| 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" }` |
## CSV Format
The default CSV format is:
- `\r\n` as line ending
- All non-numeric fields are surrounded by `"`
- If you need a `"` in the value, use `""` (double quote)
- Fields are separated by comma (`,`)
## Usage Example
This example uses the CSV example from above.
```python
from pytest_csv_params.decorator import csv_params
@csv_params(
data_file="/data/test-lib/cases/addition.csv",
id_col="ID#",
data_casts={
"part_a": int,
"part_b": int,
"expected_result": int,
},
)
def test_addition(part_a, part_b, expected_result):
assert part_a + part_b == expected_result
```
Shorthand example (no ID col, only string values):
```python
from pytest_csv_params.decorator import csv_params
@csv_params("/data/test-lib/cases/texts.csv")
def test_texts(text_a, text_b, text_c):
assert f"{text_a}:{text_b}" == text_c
```
### More complex example
This example features nearly all things the plugin has to offer. You find this example also in the test cases, see `tests/test_complex_example.py`.
The CSV file (`tests/assets/example.csv`):
```text
"Test ID","Bananas shipped","Single Banana Weight","Apples shipped","Single Apple Weight","Container Size"
"Order-7","1503","0.5","2545","0.25","1500"
"Order-15","101","0.55","1474","0.33","550"
```
The Test (`tests/test_complex_example.py`):
```python
from math import ceil
from os.path import join, dirname
from pytest_csv_params.decorator import csv_params
@csv_params(
data_file="example.csv",
base_dir=join(dirname(__file__), "assets"),
id_col="Test ID",
header_renames={
"Bananas shipped": "bananas_shipped",
"Single Banana Weight": "banana_weight",
"Apples shipped": "apples_shipped",
"Single Apple Weight": "apple_weight",
"Container Size": "container_size",
},
data_casts={
"bananas_shipped": int,
"banana_weight": float,
"apples_shipped": int,
"apple_weight": float,
"container_size": int,
},
)
def test_container_size_is_big_enough(
bananas_shipped: int, banana_weight: float, apples_shipped: int, apple_weight: float, container_size: int
) -> None:
"""
This is just an example test case for the documentation.
"""
gross_weight = (banana_weight * bananas_shipped) + (apple_weight * apples_shipped)
assert ceil(gross_weight) <= container_size
```
If you decide not to rename the columns, the test would look like this:
```python
@csv_params(
data_file="example.csv",
base_dir=join(dirname(__file__), "assets"),
id_col="Test ID",
data_casts={
"Bananas_Shipped": int,
"Single_Banana_Weight": float,
"Apples_Shipped": int,
"Single_Apple_Weight": float,
"Container_Size": int,
},
)
def test_container_size_is_big_enough(
Bananas_Shipped: int, Single_Banana_Weight: float, Apples_Shipped: int, Single_Apple_Weight: float, Container_Size: int
) -> None:
...
```
## Changelog
- 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)
## Bugs etc.
Please send your issues to `csv-params_issues` (at) `jued.de`. Please include the following:
- Plugin Version used
- Pytest version
- Python version with operating system
It would be great if you could include example code that clarifies your issue.
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.
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).
Raw data
{
"_id": null,
"home_page": "https://git.codebau.dev/pytest-plugins/pytest-csv-params",
"name": "pytest-csv-params",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "py.test,pytest,csv,params,parametrize,pytest-plugin,ddt,data-driven",
"author": "Juergen Edelbluth",
"author_email": "csv_params@jued.de",
"download_url": "https://files.pythonhosted.org/packages/ad/6f/320d535fd9de04c783b77e2274b97bf28252636384f819f82693b7ef67b4/pytest_csv_params-1.1.0.tar.gz",
"platform": null,
"description": "\n\n# pytest-csv-params\n\nA pytest plugin to parametrize data-driven tests by CSV files.\n\n[](https://git.codebau.dev/pytest-plugins/pytest-csv-params)\n[](https://pypi.org/project/pytest-csv-params/)\n[](https://pypi.org/project/pytest-csv-params/)\n[](https://pypi.org/project/pytest-csv-params/)\n[](https://pypi.org/project/pytest-csv-params/)\n\n## Requirements\n \n- Python 3.8, 3.9, 3.10, 3.11\n- pytest >= 7.4\n\nThere's no operating system dependent code in this plugin, so it should run anywhere where pytest runs.\n\n## Installation\n\nSimply install it with pip...\n\n```bash\npip install pytest-csv-params\n```\n\n... or poetry ...\n\n```bash\npoetry add --dev pytest-csv-params\n```\n\n## Documentation / User Guide\n\n**Detailed documentation can be found under\n[docs.codebau.dev/pytest-plugins/pytest-csv-params/](https://docs.codebau.dev/pytest-plugins/pytest-csv-params/)**\n\n## Usage: Command Line Argument\n\n| Argument | Required | Description | Example |\n|-------------------------|---------------|----------------------------------------------------------------------|----------------------------------------------|\n| `--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` |\n\n## Usage: Decorator\n\nSimply decorate your test method with `@csv_params` (`pytest_csv_params.decorator.csv_params`) and the following parameters:\n\n| Parameter | Type | Description | Example |\n|------------------|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|\n| `data_file` | `str` | The CSV file to use, relative or absolute path | `\"/var/testdata/test1.csv\"` |\n| `base_dir` | `str` (optional) | Directory to look up relative CSV files (see `data_file`); overrides the command line argument | `join(dirname(__file__), \"assets\")` |\n| `id_col` | `str` (optional) | Column name of the CSV that contains test case IDs | `\"ID#\"` |\n| `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` |\n| `data_casts` | `dict` (optional) | Cast Methods for the CSV Data (see \"Data Casting\" below) | `{ \"a\": int, \"b\": float }` |\n| `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\" }` | \n\n## CSV Format\n\nThe default CSV format is:\n\n- `\\r\\n` as line ending\n- All non-numeric fields are surrounded by `\"`\n- If you need a `\"` in the value, use `\"\"` (double quote)\n- Fields are separated by comma (`,`)\n\n## Usage Example\n\nThis example uses the CSV example from above.\n\n```python\nfrom pytest_csv_params.decorator import csv_params\n\n@csv_params(\n data_file=\"/data/test-lib/cases/addition.csv\",\n id_col=\"ID#\",\n data_casts={\n \"part_a\": int,\n \"part_b\": int,\n \"expected_result\": int,\n },\n)\ndef test_addition(part_a, part_b, expected_result):\n assert part_a + part_b == expected_result\n```\n\nShorthand example (no ID col, only string values):\n\n```python\nfrom pytest_csv_params.decorator import csv_params\n\n@csv_params(\"/data/test-lib/cases/texts.csv\")\ndef test_texts(text_a, text_b, text_c):\n assert f\"{text_a}:{text_b}\" == text_c\n```\n\n### More complex example\n\nThis example features nearly all things the plugin has to offer. You find this example also in the test cases, see `tests/test_complex_example.py`.\n\nThe CSV file (`tests/assets/example.csv`):\n\n```text\n\"Test ID\",\"Bananas shipped\",\"Single Banana Weight\",\"Apples shipped\",\"Single Apple Weight\",\"Container Size\"\n\"Order-7\",\"1503\",\"0.5\",\"2545\",\"0.25\",\"1500\"\n\"Order-15\",\"101\",\"0.55\",\"1474\",\"0.33\",\"550\"\n```\n\nThe Test (`tests/test_complex_example.py`):\n\n```python\nfrom math import ceil\nfrom os.path import join, dirname\n\nfrom pytest_csv_params.decorator import csv_params\n\n\n@csv_params(\n data_file=\"example.csv\",\n base_dir=join(dirname(__file__), \"assets\"),\n id_col=\"Test ID\",\n header_renames={\n \"Bananas shipped\": \"bananas_shipped\",\n \"Single Banana Weight\": \"banana_weight\",\n \"Apples shipped\": \"apples_shipped\",\n \"Single Apple Weight\": \"apple_weight\",\n \"Container Size\": \"container_size\",\n },\n data_casts={\n \"bananas_shipped\": int,\n \"banana_weight\": float,\n \"apples_shipped\": int,\n \"apple_weight\": float,\n \"container_size\": int,\n },\n)\ndef test_container_size_is_big_enough(\n bananas_shipped: int, banana_weight: float, apples_shipped: int, apple_weight: float, container_size: int\n) -> None:\n \"\"\"\n This is just an example test case for the documentation.\n \"\"\"\n\n gross_weight = (banana_weight * bananas_shipped) + (apple_weight * apples_shipped)\n assert ceil(gross_weight) <= container_size\n```\n\nIf you decide not to rename the columns, the test would look like this:\n\n```python\n@csv_params(\n data_file=\"example.csv\",\n base_dir=join(dirname(__file__), \"assets\"),\n id_col=\"Test ID\",\n data_casts={\n \"Bananas_Shipped\": int,\n \"Single_Banana_Weight\": float,\n \"Apples_Shipped\": int,\n \"Single_Apple_Weight\": float,\n \"Container_Size\": int,\n },\n)\ndef test_container_size_is_big_enough(\n Bananas_Shipped: int, Single_Banana_Weight: float, Apples_Shipped: int, Single_Apple_Weight: float, Container_Size: int\n) -> None:\n ...\n```\n\n## Changelog\n\n- A detailed changelog is here:\n [docs.codebau.dev/pytest-plugins/pytest-csv-params/pages/changelog.html](https://docs.codebau.dev/pytest-plugins/pytest-csv-params/pages/changelog.html)\n\n## Bugs etc.\n\nPlease send your issues to `csv-params_issues` (at) `jued.de`. Please include the following:\n\n- Plugin Version used\n- Pytest version\n- Python version with operating system\n\nIt would be great if you could include example code that clarifies your issue.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n## Pull Requests\n\nPull requests are always welcome. Since this Gitea instance is not open to public, just send an e-mail to discuss options.\n\nAny 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.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n## Where are the sources?\n\nThe source code is available under [git.codebau.dev/pytest-plugins/pytest-csv-params](https://git.codebau.dev/pytest-plugins/pytest-csv-params).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Pytest plugin for Test Case Parametrization with CSV files",
"version": "1.1.0",
"project_urls": {
"Changelog": "https://docs.codebau.dev/pytest-plugins/pytest-csv-params/pages/changelog.html",
"Documentation": "https://docs.codebau.dev/pytest-plugins/pytest-csv-params/",
"Homepage": "https://git.codebau.dev/pytest-plugins/pytest-csv-params",
"Issue Tracker": "https://git.codebau.dev/pytest-plugins/pytest-csv-params/issues",
"Releases": "https://git.codebau.dev/pytest-plugins/pytest-csv-params/releases",
"Repository": "https://git.codebau.dev/pytest-plugins/pytest-csv-params",
"Wiki": "https://git.codebau.dev/pytest-plugins/pytest-csv-params/wiki"
},
"split_keywords": [
"py.test",
"pytest",
"csv",
"params",
"parametrize",
"pytest-plugin",
"ddt",
"data-driven"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3c6f68fe8ad445f1d7f7b3b28e915e4fe374ed94f3eef11fe430d51abfa46ab0",
"md5": "1153d280592dd7cc04745fdd56159012",
"sha256": "10c1adf616550cceb44e6aef640cf378dc76cb7ecd66283954a5d29401b262b5"
},
"downloads": -1,
"filename": "pytest_csv_params-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1153d280592dd7cc04745fdd56159012",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 13575,
"upload_time": "2023-07-01T15:35:26",
"upload_time_iso_8601": "2023-07-01T15:35:26.617575Z",
"url": "https://files.pythonhosted.org/packages/3c/6f/68fe8ad445f1d7f7b3b28e915e4fe374ed94f3eef11fe430d51abfa46ab0/pytest_csv_params-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ad6f320d535fd9de04c783b77e2274b97bf28252636384f819f82693b7ef67b4",
"md5": "6f107a89955861ff0502ded6a65cc539",
"sha256": "78d9da960c5b939aa05dacf2eed9e20be00cdc4cd2bd76d3b03750630af1e31f"
},
"downloads": -1,
"filename": "pytest_csv_params-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "6f107a89955861ff0502ded6a65cc539",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 13193,
"upload_time": "2023-07-01T15:35:28",
"upload_time_iso_8601": "2023-07-01T15:35:28.145271Z",
"url": "https://files.pythonhosted.org/packages/ad/6f/320d535fd9de04c783b77e2274b97bf28252636384f819f82693b7ef67b4/pytest_csv_params-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-01 15:35:28",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pytest-csv-params"
}
JSON