<a id="test-advisor-instructions"></a>
<a id="id1"></a>
# Test Advisor Instructions

The Test Case and Test Data Advisors have algorithms to generate test data for different types of fields.

Test Advisor Instructions can be used to modify, or override these algorithms. Test Advisor Instructions are entered by editing a Project and choosing the 'Test Advisor Configuration' tab.

<a id="settings"></a>
## Settings

Overall settings, which will impact all relevant fields, can be specified using the 'Settings' heading.

```yaml
Settings:
  base_date: "2000-01-01"
  date_increment: 10
  log_records: 3
```

The Settings section is optional and each setting within it is optional. The settings are:

> - base_date: The date from which values for date fields will be calculated. The default is two years before the current date.
> - date_increment: (Test Data Advisor only). The Test Data Advisor will generate ascending values for a date field. The default is to increment the date by 1 day for each new value. This setting will change the increment to the specified number of days.
> - log_records: (Test Data Advisor only). The Test Data Advisor will generate the specified number of log records for each log form.

> **Important:** The indentation and spacing of lines in the Instructions is important:
>
> - There must be no spaces before the 'Settings' section header
> - There must be 2 spaces before each line in the Settings section
> - There must be 1 space after the colon separating the setting name, e.g. 'base_date' and its value

<a id="wildcard-folder"></a>
## Wildcard Folder

When generating test cases for edit checks with wild-carded folders, the folder to be used can be specified.

```yaml
WildcardFolder: SUBJECT
```

The value should be 'SUBJECT' or a valid Folder OID. If the specified value is not a valid Folder OID in the edit check's draft it will be ignored.

> **Note:** This takes precedence over most of the rules used to choose a Folder, see [How does the Test Case Advisor work?](test_case_advisor_details.html.md#test-case-advisor-details).

<a id="forms"></a>
## Forms

There can be instructions for specific forms, for example:

```yaml
Forms:
  - form_oid: AE
    log_records: 5
```

In the above example:

> - log_records: (Test Data Advisor only). The Test Data Advisor will generate the specified number of log records for the AE form. This will override the log_records value in the Settings section (if any).

<a id="datapoints"></a>
## Datapoints

There can be instructions for specific datapoints, for example:

```yaml
Datapoints:
  - field_oid: AETERM
    values:
    - Headache
    - Bleeding
    - Vomiting

  - field_oid: AESEV
    values:
    - Moderate
    - Severe

  - field_oid: AESER
    values: [1]

  - field_oid: VISITNUM
    form_oid: PRE_VISIT
    values: [0]

  - field_oid: VISITNUM
    form_oid: VISIT
    values: [1,2,3,4]

  - field_oid: VISITNUM
    form_oid: VISIT
    folder_oid: FOLLOW_UP
    values: [5]

  - field_oid: VISITDAT
    values: [-1, 5, 20, 40, 45, 60]

  - field_oid: BIRTHDAT
    low: "1960-01-01"
    high: "1980-01-01"

  - field_oid: LAB1
    low: 1000
    high: 2000
    integer: true

  - field_oid: LAB1
    record_position: 0
    form_oid: LB2
    form_repeat_number: 0
    folder_oid: UNS
    folder_repeat_number: 0
    values: [500]
```

In the above example:

> - AETERM is a text field for which the Test Advisors would normally create values using alpha characters, like 'ABCDEFGH', because there is no other information in the draft to guide the advisor when it is choosing data for a text field. The above instruction will guide the Test Advisors to use one of the 3 specified values. The Test Data Advisor will use each value in sequence after which it will choose one of the values at random. This instruction applies to the AETERM field on any form and in any folder because only the field_oid is specified.
>
> - AESEV is a dictionary field. The values in the instruction can be Coded or User Data entries. If a value does not exist in the dictionary entries it will be ignored and there will be a warning when generating data. The Test Data Advisor will use each value in sequence after which it will choose one of the values at random.
>
> - AESER is a checkbox field. This single value will constrain it to be always checked (value 1, use 0 for unchecked).
>
> - VISITNUM is an integer numeric field. There are 3 instructions in the Datapoints list for field_oid VISITNUM which have been further qualified with form_oid and folder_oid. When choosing values the Test Advisors will find the best match:
>
>   > - if the data is required for the VISITNUM field on the PRE_VISIT form then the first instruction will be used.
>   > - if the data is required for the VISITNUM field on the VISIT form in the FOLLOW_UP folder then the third instruction will be used.
>   > - if the data is required for the VISITNUM field on the VISIT form in a folder other than FOLLOW_UP the second instruction will be used.
>   > - if the data is required for the VISITNUM field on a form other than PRE_VISIT or VISIT then no instruction will be used.
>
> - VISITDAT is a date field. Values will be calculated by adding (or subtracting if the value is negative) the specified number of days to the base date. A decimal value such as 1.5 will add 36 hours to the base date if the field has a datetime format, otherwise it will add 1 day (rounding down the decimal component).
>
> - BIRTHDAT is a date field. Values in the range 01 JAN 1960 to 01 JAN 1980 (inclusive) will be used. The values must be specified in ISO format yyyy-mm-dd surrounded by double quotes.
>
> - LAB1 is a decimal numeric field. The values will be in the range 1000 to 200 (inclusive) and will be integers (even though the field data format has decimal places), except for datapoint UNS[0].LB2[0].LAB1[0] which will have value 500.

> **Note:** Invalid values will be ignored. For example a high value of '01 JAN 2020' for a date field will be ignored because the value is not in ISO format.

> **Note:** Values will be ignored if they are not relevant for the field. For example low or high values will be ignored for text fields.

List of values can be inline, separated by commas:

```yaml
Datapoints:
  - field_oid: AETERM
    values: [Headache,Bleeding,Vomiting]
```

or on separate lines (where the values can include commas):

```yaml
Datapoints:
  - field_oid: AETERM
    values:
    - Headache
    - Bleeding
    - Vomiting, frequent
    - Vomiting, infrequent
```

<a id="matrices"></a>
## Matrices

There can be instructions to control which Matrices are excluded when the Test Case Advisor chooses a Folder in an Edit Check which has a wild-carded Folder (see [How does the Test Case Advisor work?](test_case_advisor_details.html.md#test-case-advisor-details)).

```yaml
Settings:

ExcludedMatrices:
  - UNIQUE
  - ALLFORMS1
  - ALLFORMS2
```