fix: add documentation on reporter usage (#81)

README.md

@@ -4,6 +4,126 @@
 > This is still a work in progress. Any usage of this package is subject to
 > change without notice.
 
+Helper package for generating reports for use with the **D2L test reporting
+framework**.
+
+## Installation
+
+```console
+npm install d2l-test-reporting
+```
+
+## Usage
+
+This library provides a reporters for many of the test execution frameworks we
+use, if one for your test runner framework isn't provided please [file an issue]
+so we can look into adding it to our set of reporters.
+
+### Reporters
+
+#### [Mocha]
+
+Please consult the [official documentation for Mocha] to see how
+to use reporters. Below is an example of how to add the reporter provided by
+this package.
+
+```js
+module.exports = {
+  spec: 'test/*.test.js',
+  reporter: 'd2l-test-reporting/reporters/mocha.cjs',
+  reporterOptions: [
+    'reportPath=./d2l-test-report.json', // optional
+    'reportConfigurationPath=./d2l-test-reporting.config.json' // optional
+  ]
+};
+```
+
+##### Inputs
+
+* `reportPath`: path to output the reporter to, relative to current working
+  directory. Not required. Defaults to `./d2l-test-report.json`.
+* `reportConfigurationPath`: path to the D2L test reporting configuration file
+  for mapping test type, experience and tool to test code. Not required.
+  Defaults to `./d2l-test-reporting.config.json`.
+
+#### [Playwright]
+
+Please consult the [official documentation for Playwright] to see how
+to use reporters. Below is an example of how to add the reporter provided by
+this package.
+
+```js
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  reporter: [
+    [
+      'd2l-test-reporting/reporters/playwright.js',
+      {
+        reportPath: './d2l-test-report.json', // optional
+        reportConfigurationPath: './d2l-test-reporting.config.json' // optional
+      }
+    ],
+    ['list']
+  ],
+  testDir: '../',
+  testMatch: '*.test.js',
+  projects: [{
+    name: 'firefox',
+    use: devices['Desktop Firefox'],
+    testMatch: 'firefox/*.test.js'
+  }]
+});
+```
+
+> [!WARNING]
+> Currently the [`merge-reports`] command is not fully supported due to a lack
+> of browser/launcher information preservation with the `blob` reporter. If you
+> are using a GitHub matrix run this may result in partial data showing in the
+> reporting dashboard as it becomes available.
+
+##### Inputs
+
+* `reportPath`: path to output the reporter to, relative to current working
+  directory. Not required. Defaults to `./d2l-test-report.json`.
+* `reportConfigurationPath`: path to the D2L test reporting configuration file
+  for mapping test type, experience and tool to test code. Not required.
+  Defaults to `./d2l-test-reporting.config.json`.
+
+#### [`@web/test-runner`]
+
+Please consult the [official documentation for `@web/test-runner`] to see how
+to use reporters. Below is an example of how to add the reporter provided by
+this package.
+
+```js
+import { defaultReporter } from '@web/test-runner';
+import { reporter } from 'd2l-test-reporting/reporters/web-test-runner.js';
+
+export default {
+  reporters: [
+    defaultReporter(),
+    reporter({
+      reportPath: './d2l-test-report.json', // optional
+      reportConfigurationPath: './d2l-test-reporting.config.json' // optional
+    })
+  ],
+  files: 'test/component-*.test.js',
+  groups: [{
+    name: 'group',
+    files: 'test/group/component-*.test.js'
+  }]
+};
+```
+
+##### Inputs
+
+* `reportPath`: path to output the reporter to, relative to current working
+  directory. Not required. Defaults to `./d2l-test-report.json`.
+* `reportConfigurationPath`: path to the D2L test reporting configuration file
+  for mapping test type, experience and tool to test code. Not required.
+  Defaults to `./d2l-test-reporting.config.json`.
+
 ## Developing
 
 After cloning the repository make sure to install dependencies.
@@ -47,3 +167,13 @@ npm run test:unit
 # integration tests only
 npm run test:integration
 ```
+
+<!-- links -->
+[file an issue]: https://github.com/Brightspace/test-reporting-node/issues/new
+[official documentation for Mocha]: https://mochajs.org/api/mocha#reporter
+[official documentation for Playwright]: https://playwright.dev/docs/test-reporters
+[official documentation for `@web/test-runner`]: https://modern-web.dev/docs/test-runner/reporters/overview
+[Mocha]: https://mochajs.org
+[Playwright]: https://playwright.dev
+[`@web/test-runner`]: https://modern-web.dev/docs/test-runner/overview
+[`merge-reports`]: https://playwright.dev/docs/test-sharding#merge-reports-cli

package.json

@@ -1,7 +1,7 @@
 {
   "name": "d2l-test-reporting",
   "version": "0.0.24",
-  "description": "Node helper package for the test reporting framework",
+  "description": "Helper package for generating reports for use with the D2L test reporting framework",
   "author": "D2L Corporation",
   "license": "Apache-2.0",
   "repository": "https://github.com/Brightspace/test-reporting-node.git",

test/integration/data/config/mocha.cjs

@@ -2,7 +2,7 @@ module.exports = {
 	spec: 'test/integration/data/mocha-*.test.js',
 	retries: 3,
 	reporter: 'src/reporters/mocha.cjs',
-	'reporter-option': [
+	reporterOptions: [
 		'reportPath=./d2l-test-report-mocha.json',
 		'reportConfigurationPath=./test/integration/data/config/d2l-test-reporting.json'
 	]