Configuration¶

Decorator Parameters¶

These are the parameters for the decorator 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" }`
`reuse_id_col`	`bool` (optional)	Allows to re-use the ID column as test data column (since 1.3.0), defaults to `False` for backwards compatibility	`True`

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.

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:

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

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:

"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 csv.Dialect. A dialect defines how a CSV file looks like.

The default dialect is pytest_csv_params.dialect.CsvParamsDefaultDialect.

A dialect consists of the following settings:

Setting	Default value in `CsvParamsDefaultDialect`
`delimiter`	`","`
`doublequote`	`True`
`escapechar`	`None`
`lineterminator`	`"\r\n"`
`quotechar`	`'"'`
`quoting`	`csv.QUOTE_ALL`
`skipinitialspace`	`True`
`strict`	`True`

See Usage 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.

Rule of thumb

You can use any method that accepts a single str parameter. It can return anything you need.
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:
    ...

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:

"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(flux_setting: str, power_level: str) -> None:
    ...

Warning

data_casts dictionary keys must match the renamed column names!

`reuse_id_col`¶

Setting this option to True allows using the column defined as id_col to be also used as test data source. This feature has been added in v1.3.0, and defaults to False to ensure backwards compatibility. Maybe this changes to be the default in version 2.

Example:

from pytest_csv_params.decorator import csv_params

@csv_params(
    data_file="test.csv",
    id_col="Test Case ID#",
    reuse_id_col=True,
    header_renames={
        "Flux Compensator Setting": "flux_setting",
        "Power Level": "power_level",
        "Test Case ID#": "test_id",
    },
)
def test_something_with_reusing_id_col(flux_setting: str, power_level: str, test_id: str) -> None:
    ...

There’s also a shortcut for that behaviour:

from pytest_csv_params.shortcut import csv_params_reusing_id_col as csv_params

@csv_params(
    data_file="test.csv",
    id_col="Test Case ID#",
    header_renames={
        "Flux Compensator Setting": "flux_setting",
        "Power Level": "power_level",
        "Test Case ID#": "test_id",
    },
)
def test_something_with_reusing_id_col(flux_setting: str, power_level: str, test_id: str) -> None:
    ...

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

Configuration¶

Decorator Parameters¶

Overview¶

Detailed Description¶

data_file¶

base_dir¶

id_col¶

dialect¶

data_casts¶

header_renames¶

reuse_id_col¶

Command Line Arguments¶

Overview¶

Detailed Description¶

--csv-params-base-dir¶

How a CSV file is found¶

`data_file`¶

`base_dir`¶

`id_col`¶

`dialect`¶

`data_casts`¶

`header_renames`¶

`reuse_id_col`¶

`--csv-params-base-dir`¶