# Spec tests

These tests specify the expected behaviour of ehrQL, and by extension, the query model.

They are also used to generate documentation.

## Table of Contents

`toc.py` defines the Table of Contents for the documentation generated by tests. A new spec test

subdirectory or file must be defined here in order for it to appear in the docs.

## Folder structure

Within the spec directory, each test directory is considered a chapter in the docs, each file

is considered to be a section, and each test is a paragraph.

e.g.

```

tests

    ├── spec

    │   ├── aggregate_frame                       <-- chapter

    │   │   ├── __init__.py                       <-- contains chapter title

    │   │   ├── test_count_for_patient.py         <-- section

    │   │   └── test_exists_for_patient.py        <-- section

```

### Titles

Chapter titles are specified with a `title` attribute in the test directory's `__init__.py`.

Section titles are specified with a `title` attribute in each test file.

Paragraph titles are extracted from the test names, or from a `title` attribute in the test

function.

E.g. `test_count_for_patient.py` contains 2 tests:

- `test_count_for_patient_on_event_frame()`

- `test_count_for_patient_on_patient_frame()`

Assuming this is included in `toc.py`, the following structure will be generated in the docs:

> 1. Aggregating event and patient frames  # from `title` in `aggregate_frame/__init__.py`

> 1.1 Counting the rows for each patient  # from `title` in `aggregate_frame/test_count_for_patient.py`

> 1.1.1 Count for patient on event frame  # from test name

> 1.1.2 Count for patient on patient frame  # from test name

### Additional text

Optional additional text can be included under a Chapter, Section or Paragraph title in the

documentation as follows:

- Chapter: add a `text` attribute in the test directory's `__init__.py`.

- Section: add a `text` attribute in a test file.

- Paragraph: add a docstring to the test function.

## Test structure

Spec tests follow a standardised structure in order to allow documentation generation.  Each

spec test uses the `spec_test` fixture, which has the following components:

```

spec_test(

    table_data,                          # a dict (see below) defining the tables in the test database

    e.where(e.b1).i1.sum_for_patient(),   # the ehrQL code being tested

    {                                    # expected results

        1: (101 + 102),

        2: 201,

    },

)

```

### Defining table data

Each test must define a dict named `table_data`, with keys `e` (event level data, with multiple rows

per patient) and/or `p` (patient level data, with one row per patient).

This sets up the test data.  The first column is always patient ID and must be of integer type;

it can be given a heading in the test for readability if desired, but it does not require one.

Subsequent columns must take one of a discrete set of names, which indicate the type of the column

in the test database.

See `tests/spec/tables.py` for available column names and types.

E.g. The following table data dict sets up:

- an event table with an integer column `i1` and a boolean column `b1`, with 3 rows for patient 1,

  and 2 rows for patient 2

- a patient table with a date column `d1` with rows for 3 patients, 2 of which also appear in the

  event table.

```

table_data = {

    e: """

          |  i1 |  b1

        --+-----+-----

        1 | 101 |  T

        1 | 102 |  T

        1 | 103 |  F

        2 | 201 |  T

        2 | 202 |

    """,

    p: """

          |  d1

        --+-----------

        1 | 1990-01-02

        2 | 1990-01-02

        3 |

    """

}

```

### Defining the ehrQL code to return a series

Define the ehrQL code that's being tested, using the table data. This should always be

expected to return a Series.

e.g. in the table data above, to get the sum of the `i1` column where `b1` is True:

```e.where(e.b1).i1.sum_for_patient()```

### Expected results

Describe the expected resulsts as a dict, with patient IDs as keys.

e.g. in the example above, the expected sums would be:

```

{

    1: (101 + 102),

    2: 201,

}

```