[docs] Docs Metadata

docs/articles/documentation/extending-testcafe/reporter-plugin/reporter-methods.md

@@ -48,38 +48,41 @@ reportTaskStart (startTime, userAgents, testCount) {
 Fires each time a fixture starts.
 
 ```text
-reportFixtureStart (name, path)
+reportFixtureStart (name, path, meta)
 ```
 
 Parameter | Type   | Description
 --------- | ------ | --------------------------------
 `name`    | String | The test fixture name.
 `path`    | String | The path to a test fixture file.
+`meta`    | Object | The [fixture metadata](../../test-api/test-code-structure.md#fixture-metadata).
 
 **Example**
 
 ```js
-reportFixtureStart (name) {
+reportFixtureStart (name, path, meta) {
     this.currentFixtureName = name;
-    this.write(`Starting fixture: ${name}`)
+    this.currentFixtureMeta = meta;
+    this.write(`Starting fixture: ${name} ${meta.fixtureID}`)
         .newline();
 }
 
-//=> Starting fixture: First fixture
+//=> Starting fixture: First fixture f-0001
 ```
 
 ## reportTestDone
 
 Fires each time a test ends.
 
 ```text
-reportTestDone (name, testRunInfo)
+reportTestDone (name, testRunInfo, meta)
 ```
 
 Parameter     | Type   | Description
 ------------- | ------ | -------------------------------------------------------------
 `name`        | String | The test name.
 `testRunInfo` | Object | The object providing detailed information about the test run.
+`meta`        | Object | The [test metadata](../../test-api/test-code-structure.md#test-metadata).
 
 The `testRunInfo` object has the following properties.
 
@@ -94,7 +97,7 @@ Property         | Type             | Description
 **Example**
 
 ```js
-reportTestDone (name, testRunInfo) {
+reportTestDone (name, testRunInfo, meta) {
     const hasErr = !!testRunInfo.errs.length;
     const result = testRunInfo.skipped ? 'skipped' : hasErr ? `passed` : `failed`;
 
@@ -108,11 +111,14 @@ reportTestDone (name, testRunInfo) {
     if (testRunInfo.screenshotPath)
         title += ` (screenshots: ${testRunInfo.screenshotPath})`;
 
+    if (meta.severity)
+        title += ' (meta.severity)';
+
     this.write(title)
         .newline();
 }
 
-//=> failed First fixture - First test in first fixture (unstable) (screenshots: /screenshots/1445437598847)
+//=> failed First fixture - First test in first fixture (unstable) (screenshots: /screenshots/1445437598847) (critical)
 //=> passed First fixture - Second test in first fixture (screenshots: /screenshots/1445437598847)
 //=> failed First fixture - Third test in first fixture
 //=> skipped First fixture - Fourth test in first fixture

docs/articles/documentation/test-api/test-code-structure.md

@@ -14,6 +14,8 @@ This topic contains the following sections.
   * [Setting Test Speed](#setting-test-speed)
   * [Setting Page Load Timeout](#setting-page-load-timeout)
 * [Specifying the Start Webpage](#specifying-the-start-webpage)
+* [Specifying Testing Metadata](#specifying-testing-metadata)
+  * [Using Metadata in Reports](#using-metadata-in-reports)
 * [Initialization and Clean-Up](#initialization-and-clean-up)
   * [Test Hooks](#test-hooks)
     * [Sharing Variables Between Test Hooks and Test Code](#sharing-variables-between-test-hooks-and-test-code)
@@ -40,7 +42,7 @@ Parameter     | Type   | Description
 ------------- | ------ | ------------------------
 `fixtureName` | String | The name of the fixture.
 
-This function returns the `fixture` object that allows you to configure the fixture - specify the [start webpage](#specifying-the-start-webpage) and [initialization and clean-up code](#initialization-and-clean-up) for tests included to the fixture.
+This function returns the `fixture` object that allows you to configure the fixture - specify the [start webpage](#specifying-the-start-webpage), [metadata](#specifying-testing-metadata) and [initialization and clean-up code](#initialization-and-clean-up) for tests included to the fixture.
 
 > [Tests](#tests) that constitute a fixture go after this declaration.
 
@@ -277,6 +279,76 @@ fixture `MyFixture`
     .page `../my-project/index.html`;
 ```
 
+## Specifying Testing Metadata
+
+TestCafe allows you to specify additional information for tests in the form of *key-value metadata* and use it in reports.
+
+To define metadata, use the `meta` method. You can call this method both for a fixture and a test.
+
+The `meta` method allows you to specify one or several metadata entries:
+
+* Specifying one metadata entry.
+
+    ```js
+    fixture.meta('key1', 'value1')
+    ```
+
+    ```js
+    test.meta('key2', 'value2')
+    ```
+
+    Parameter | Type   | Description
+    --------- | ------ | -----------------
+    `name`    | String | The name of the metadata entry
+    `value`   | String | The value of the metadata entry
+
+* Specifying a set of metadata entries.
+
+    ```js
+    fixture.meta({ key1: 'value1', key2: 'value2', key3: 'value3' })
+    ```
+
+    ```js
+    test.meta({ key4: 'value1', key5: 'value2', key6: 'value3' })
+    ```
+
+    Parameter  | Type   | Description
+    ---------- | ------ | -----------------
+    `metadata` | Object | Key-value pairs
+
+**Examples**
+
+```js
+fixture 'MyFixture'
+    .meta('fixtureID', 'f-0001')
+    .meta({ author: 'John', creationDate: '05/03/2018' });
+```
+
+```js
+test
+    .meta('testID', 't-0005')
+    .meta({ severity: 'critical', testedAPIVersion: '1.0' });
+    ('MyTest', async t => { /* ... */});
+```
+
+All metadata entries specified for a fixture are available in tests included to this fixture.
+
+If you specified the same entries in the `test.meta` and `fixture.meta` methods, the `test.meta` method call overrides values for these entries. The following example demonstrates the case when the `test.meta` method call overrides the **creationDate** entry.
+
+```js
+fixture `My fixture`
+    .meta('creationDate', '05/03/2018')
+    .page `http://www.example.com/`;
+
+test
+    .meta('creationDate', '05/04/2018'); // The value of the creationDate entry is '05/04/2018'
+    ('MyTest', async t => { /* ... */});
+```
+
+### Using Metadata in Reports
+
+You can include testing metadata to reports using a [custom reporter](../extending-testcafe/reporter-plugin/README.md). The reporter's [reportFixtureStart](../extending-testcafe/reporter-plugin/reporter-methods.md#reportfixturestart) and [reportTestDone](../extending-testcafe/reporter-plugin/reporter-methods.md#reporttestdone) methods can access to the fixture and test metadata.
+
 ## Initialization and Clean-Up
 
 TestCafe allows you to specify functions that will be executed before a fixture or test is started and after it is finished.

docs/nav/nav-menu.yml

@@ -56,6 +56,11 @@
         url: /documentation/test-api/test-code-structure.md#setting-test-speed
     - name: Specifying the Start Webpage
       url: /documentation/test-api/test-code-structure.md#specifying-the-start-webpage
+    - name: Specifying Testing Metadata
+      url: /documentation/test-api/test-code-structure.md#specifying-testing-metadata
+      content:
+      - name: Using Metadata in Reports
+        url: /documentation/test-api/test-code-structure.md#using-metadata-in-reports
     - name: Initialization and Clean-Up
       url: /documentation/test-api/test-code-structure.md#initialization-and-clean-up
       content: