metadata docs

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,10 @@ 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)
+  * [Fixture Metadata](#fixture-metadata)
+  * [Test Metadata](#test-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 +44,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 +281,54 @@ fixture `MyFixture`
     .page `../my-project/index.html`;
 ```
 
+## Specifying Testing Metadata
+
+TestCafe allows you to specify additional information for fixtures and tests in the form of *field-value metadata*.
+
+### Fixture Metadata
+
+You can specify metadata for a fixture by using the `meta` method in the [fixture declaration](#fixtures).
+
+```js
+fixture.meta({ field1: 'value1', field2: 'value2', field3: 'value3' });
+```
+
+Parameter  | Type   | Description
+---------- | ------ | -----------------
+`metadata` | Object | Field-value pairs
+
+**Example**
+
+```js
+fixture 'MyFixture'
+    .meta('fixtureID', 'f-0001')
+    .meta({ field2: 'value2', field3: 'value3' });
+```
+
+### Test Metadata
+
+You can specify metadata for an individual test by using the `test.meta` method.
+
+```js
+test.meta({ field1: 'value1', field2: 'value2', field3: 'value3' });
+```
+
+Parameter  | Type   | Description
+---------- | ------ | -----------------
+`metadata` | Object | Field-value pairs
+
+**Example**
+
+```js
+test
+    .meta({ testID: 't-0005', severity: 'critical' });
+    ('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 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,15 @@
         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: Fixture Metadata
+        url: /documentation/test-api/test-code-structure.md#fixture-metadata
+      - name: Test Metadata
+        url: /documentation/test-api/test-code-structure.md#test-metadata
+      - 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: