Custom fields

Custom fields are arbitrary key-value pairs that can be assigned to test cases. Similar to a tag, the actual meaning of a custom field is project-specific.

The general purpose of custom fields is to help filter and group test cases. You can use them:

• to group test cases by specific values in custom trees,
• to search for test cases using filters,
• to filter test cases via AQL (e.g., when creating test plans).

To start using a new custom field:

1. As an administrator, declare the custom field.
2. As an administrator or a project owner, add the custom field to the project.
3. As an administrator or a project owner, add global or project values for the custom field.
4. As a project owner or a test author, edit values for test cases manually or automatically.

System fields

To each project in Allure TestOps, some system fields are added automatically. This includes:

• Epic, Feature, Story — used by default for the “Features” tree,
• Suite — used by default for the “Suites” tree,
• Component — not used by default but often used for custom trees or filters.

The system fields cannot be removed from a project. You can, however, add or remove mappings for any field, see Setting custom fields automatically.

The labels in the default mappings for Epic, Feature, Story, and Suite match the labels generated by the standard functions in most Allure adapters.

Declaring custom fields

Before a custom field can be added to individual projects, it must be declared globally by an Allure TestOps instance administrator.

To declare a new custom field:

1. Go to Administration → Custom Fields.

2. Click + Field.

3. Enter a human-readable name for the new field.

4. Select a field type: Single-select or Multi-select, and click Create.

   Once created, the field type cannot be changed.

To rename or remove an existing custom field, click ⋯ in the upper-right corner and select the desired action.

Adding custom fields to a project

Once you have declared a custom field in the Allure TestOps instance, you need to add it to your project to start using it. This can be done either from the administration panel by an administrator or from the project settings by the project owner.

• From the administration panel
• From the project settings

1. Go to Administration → Custom Fields.
2. Select the field you want to add to a project.
3. Go to the Projects tab.
4. Click Add to projects.
5. In the dialog that appears, select the projects for which the field should be available, then click Add.

1. Go to Settings → Custom Fields.
2. Click + Field.
3. In the dialog that appears, select the custom fields that should be available for the project, then click Add.

Required field

Required field is a setting that forces users to specify a value for a custom field in every test case of the project.

The Required field setting for a custom field can be enabled by:

• instance administrator – for all projects where this custom field is added or for each project individually;
• project owner – only for their own project.

• From the administration panel
• From the project settings

1. Go to Administration → Custom Fields.
2. Select the custom field you want to mark as required.
3. Click ⋯ in the upper-right corner or go to the Projects tab and click ⋯ next to the project name.
4. Turn on the Required toggle.

1. Go to Settings → Custom Fields.
2. Select the field you want to mark as required.
3. Click ⋯ in the upper-right corner.
4. Turn on the Required toggle.

A project owner cannot disable the Required setting if it was enabled by an administrator.

Required field features:

• The required field is always displayed in the test case details.
• If a required field is left blank, the system displays the message "No values".
• Users cannot save changes to custom field settings until all required fields are completed.

Adding custom field values

There are two types of custom field values:

• Global value is created by the instance administrator and available in all projects where the corresponding custom field is used.
• Project value is created by the project owner and available only within that specific project.

• From the administration panel
• From the project settings

1. Go to Administration → Custom Fields.
2. Select the custom field you want to add a value for.
3. Go to the Global values tab and click + Value.
4. Enter a name and optionally enable the Default value setting.
5. Click Create.

1. Go to Settings → Custom Fields.
2. Select the custom field you want to add a value for.
3. Go to the Project values tab and click + Value.
4. Enter a name and optionally enable the Default value setting.
5. Click Create.

An instance administrator can convert project values to global. To do this:

1. Go to Administration → Custom Fields.
2. Select the field containing the value you want to set as global.
3. Go to the Project values tab.
4. Click ⋯ next to the value and select Set as global.

Locking values

Lock values is a setting that restricts custom field selections to predefined global and project values.

The Lock values setting can be enabled for a custom field by:

• instance administrator — for all projects containing this field or for individual projects separately;
• project owner — only for their own project.

The Lock values setting cannot be enabled for an empty custom field.

• From the administration panel
• From the project settings

1. Go to Administration → Custom Fields.
2. Select the custom field you want to lock a value for.
3. Click ⋯ in the upper-right corner or go to the Projects tab and click ⋯ next to the project name.
4. Turn on the Lock values toggle.

1. Go to Settings → Custom Fields.
2. Select the custom field you want to lock a value for.
3. Click ⋯ in the upper-right corner.
4. Turn on the Lock values toggle.

When an instance administrator enables Lock values setting for a custom field, a project owner cannot:

• disable this setting in project settings;
• create new values for this custom field.

Default value

Both global and project custom field values can be marked as a Default value – it will be automatically assigned to the new test cases in all projects where this custom field is used.

The default value can be enabled either from the administration panel by an administrator or from the project settings by the project owner.

• From the administration panel
• From the project settings

1. Go to Administration → Custom Fields.
2. Select the custom field for which you want to enable a default value.
3. On the Global values tab, click ⋯ next to the global value name and select Set as default.

1. Go to Settings → Custom Fields.
2. Select the custom field for which you want to enable a default value.
3. On the Project values tab, click ⋯ next to the project value name and select Set as default.

Project default values override global default values. The system falls back to a global default value when there is no project default value.

Merging values

An instance administrator can merge one or multiple project values in the administration panel:

• with an existing global value;
• into a new global value.

A project owner can merge one or multiple project values in the project settings:

• with an existing global value;
• with another existing project value;
• into a new project value.

You cannot merge values for a custom field that has Lock values setting enabled.

• From the administration panel
• From the project settings

1. Go to Administration → Custom Fields.
2. Select the custom field containing values you want to merge.
3. Go to the Project values tab.
4. Click ⋯ next to the target value and select Merge into.
5. Choose one of these options:
   • Select an existing global value from the list and click Yes, merge.
   • Click New global value to create and set this new global value as a merge destination.

1. Go to Settings → Custom Fields.
2. Select the custom field containing values you want to merge.
3. On the Project values tab, click ⋯ next to the target value and select Merge into.
4. Choose one of these options:
   • Select an existing global or project value from the list and click Yes, merge.
   • Click New project value to create and set this new project value as a merge destination.

Setting custom field values in test cases

Allure TestOps provides multiple ways of setting the values for a test case's custom fields:

• set values manually for one or several test cases (supported for the manual QA; can be enabled for the automation QA);
• set values manually using test case trees (supported for both the manual QA and the automation QA);
• set values automatically (supported for the automation QA only).

To manually change the values of custom fields for automated test cases, change your project's upload policy.

Set values manually for one or several test cases

To add a custom field value to a test case:

1. Go to the Test cases section of your project.

2. Open a test case.

3. On the right side of the screen, next to Fields, click the pencil icon.

4. In the dialog that appears, edit the table of custom field values.

   In each row, the Custom Field must be a field name previously added to the project, and Value can contain one or more arbitrary text values.

   

5. Click Submit to save the changes.

To add custom field values to several test cases at once, use the Add metadata item in the bulk actions menu. As a result:

• Allure TestOps will add the specified values to each selected test case.
• Existing values will not be affected.

To remove certain custom field values from several test cases at once, use the Remove metadata item in the bulk actions menu. As a result:

• Allure TestOps will remove the specified values from each selected test case where they are present.
• Other values will not be affected.

Set values manually using trees

Trees is an Allure TestOps feature that allows you to work with custom fields as easily as with files and folders on your PC.

Each folder in a tree is a set of test cases grouped by the value of a specific custom field. You can drag and drop test cases from one folder to another, change the custom field value of all test cases in a folder, create new test cases with the required value, etc.

You can find more information about working with trees in the Trees article.

Set values automatically

1. Go to Settings → Custom Fields.

2. Select the custom field that should be loaded from test results.

3. Click New mapping.

4. In the dialog that appears, enter the name of the label and click Create.

5. In your test code, use the specified label name to set the values.

   • Test code
   • Test result

   The example is written in Java.

   @Test
   public void testAuthentication() {
       Allure.label("component", "Core");
       Allure.label("version", "1.23");
       // ...
   }
   

   Depending on the language and framework you use, there can be multiple ways to define labels for your test cases. See your Allure adapter's reference for more details.

   The example shows a part of a test result file that will be generated when running the test. After uploading the test results, Allure TestOps will use the values from this file.

   "labels": [
     { "name": "component", "value": "Core" },
     { "name": "version", "value": "1.23" }
   ],
   

   For more details on the file format, see the Allure Report documentation.

Once the mapping is configured and the code is updated where necessary, make sure to run a new launch and close it to apply the changes.

Changing upload policy

If you want to change the values of custom fields for automated test cases using the web interface instead of specifying values in test results, you can change your upload policy to ignore custom fields values from test results.

1. Open your project.
2. Go to Settings → Upload.
3. Click the + Create button.
4. Under Field, select custom_field.
5. Under Policy, select from_test_case.
6. Click Submit.