pytest-csv-params/docs/pages/config.md

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)	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.

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.

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:

"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:

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 to learn how to create your own decorator that would always use your own specific CSV file dialect.

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.

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:

"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:

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:
    ...

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:

"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:

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:
    ...

`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_files, 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

+-----------------------------------+             /-----------------------------------\
| 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    |
\-----------------------------------/