PE-3634 Report Submitter

docs/format/report.md

@@ -188,4 +188,4 @@ stored in [AWS Timestream], please see [Storage Schema].
 
 <!-- links -->
 [AWS Timestream]: https://aws.amazon.com/timestream
-[Storage Schema]: https://github.com/Brightspace/test-reporting-action/blob/main/docs/storage-schema.md
+[Storage Schema]: ./storage-schema.md

docs/format/storage-schema.md

@@ -0,0 +1,173 @@
+# Storage Schema
+
+All report data once submitted to the back-end is stored in [AWS Timestream].
+The data is split across 2 tables ([`summary`](#summary) and
+[`details`](#details)) to better store common items, reduce duplication and
+allow for more targeted queries. Below is a breakdown of the various tables and
+their columns as well as the corresponding JSON path within the report format
+the data is sourced from. The current `measure_name` for both the
+[`summary`](#summary) and [`details`](#details) tables is `report_v3_bc` — the
+`_bc` suffix indicates the `details` records still carry deprecated dimensions
+(`experience`, `type`, `tool`, `timeout`) for backwards compatibility. Once
+those dimensions are removed the suffix will be dropped to `report_v3` on both
+tables. Old format records will be marked with `report_v2`, `report_v2_bc` or
+`*_test_run` and can require special handling. See notes under various
+**Removed** sections for details.
+
+> [!NOTE]
+  The storage schema is always based on the [latest report schema] and uses the
+  [auto upgrading report construct] to make sure it's always the latest schema.
+
+## Tables
+
+### `summary`
+
+This table contains all of the information that is common to a test run as well
+as some rolled up counts of various test statuses.
+
+#### Timestamp
+
+* `time` (`TIMESTAMP`): Stored with **millisecond** precision, sourced from
+  report JSON `report.summary.started`.
+
+#### Measures
+
+* `duration_total` (`BIGINT`): Stored as **milliseconds** from report JSON
+  `report.summary.duration.total`.
+* `status` (`VARCHAR`): Will either be `passed` or `failed`, sourced from report
+  JSON `report.summary.status`.
+* `count_passed` (`BIGINT`): Sourced from report JSON
+  `report.summary.count.passed`.
+* `count_failed` (`BIGINT`): Sourced from report JSON
+  `report.summary.count.failed`.
+* `count_skipped` (`BIGINT`): Sourced from report JSON
+  `report.summary.count.skipped`.
+* `count_flaky` (`BIGINT`): Sourced from report JSON
+  `report.summary.count.flaky`.
+
+> [!WARNING]
+  Anything marked with **[deprecated]** should be moved away from. Sending of
+  this column will be removed in the near future.
+
+##### Removed
+
+* `total_duration` (`BIGINT`): Starting with records that have `measure_name` of
+  `report_v2` this field will no longer be present. Please use `duration_total`
+  instead. If wanting to get data from records prior to `report_v2` please use
+  `COALESCE(total_duration, duration_total)` to get a reasonable value.
+
+#### Dimensions
+
+> [!NOTE]
+  All dimensions are stored as `VARCHAR` as it is the only format available.
+
+* `report_id`: Sourced from report JSON `report.id`.
+* `github_organization`: Sourced from report JSON
+  `report.summary.github.organization`.
+* `github_repository`: Sourced from report JSON
+  `report.summary.github.repository`.
+* `github_workflow`: Sourced from report JSON `report.summary.github.workflow`.
+* `github_run_id`: Sourced from report JSON `report.summary.github.runId`.
+* `github_run_attempt`: Sourced from report JSON
+  `report.summary.github.runAttempt`.
+* `git_branch`: Sourced from report JSON `report.summary.git.branch`.
+* `git_sha`: Sourced from report JSON `report.summary.git.sha`.
+* `operating_system`: Will be one of `windows`, `linux` or `mac`, sourced from
+  report JSON `report.summary.operatingSystem`.
+* `framework`: Sourced from report JSON `report.summary.framework`.
+* `lms_build_number` (`NULLABLE`): Sourced from report JSON
+  `report.summary.lms.buildNumber`.
+* `lms_instance_url` (`NULLABLE`): Sourced from report JSON
+  `report.summary.lms.instanceUrl`.
+
+> [!WARNING]
+  Anything marked with **[deprecated]** should be moved away from. Sending of
+  this column will be removed in the near future.
+
+### `details`
+
+This table contains information about each individual test that was run. You can
+map to the [`summary`](#summary) data via the `report_id` if you need a
+combination of the data.
+
+#### Timestamp
+
+* `time` (`TIMESTAMP`): Stored with **millisecond** precision, sourced from
+  report JSON `report.details[].started`.
+
+#### Measures
+
+* `duration_final` (`BIGINT`): Stored as **milliseconds**, sourced from report
+  JSON `report.details[].duration.final`.
+* `duration_total` (`BIGINT`): Stored as **milliseconds**, sourced from report
+  JSON `report.details[].duration.total`.
+* `retries` (`BIGINT`): Sourced from report JSON `report.details[].retries`.
+* `status` (`VARCHAR`): Will be one of `passed`, `skipped` or `failed`, sourced
+  from report JSON `report.details[].status`.
+* `configuration_timeout` (`BIGINT`, `NULLABLE`): Stored as **milliseconds**, sourced
+  from report JSON `report.details[].configuration.timeout`.
+
+> [!WARNING]
+  Anything marked with **[deprecated]** should be moved away from. Sending of
+  this column will be removed in the near future.
+
+##### Removed
+
+* `duration` (`BIGINT`): Starting with records that have `measure_name` of
+  `report_v2` this field will no longer be present. Please use `duration_final`
+  instead. If wanting to get data from records prior to `report_v2` please use
+  `COALESCE(duration, duration_final)` to get a reasonable value.
+* `total_duration` (`BIGINT`): Starting with records that have `measure_name` of
+  `report_v2` this field will no longer be present. Please use `duration_total`
+  instead. If wanting to get data from records prior to `report_v2` please use
+  `COALESCE(total_duration, duration_total)` to get a reasonable value.
+
+#### Dimensions
+
+> [!NOTE]
+  All dimensions are stored as `VARCHAR` as it is the only format available.
+
+* `report_id`: Sourced from report JSON `report.id`.
+* `name`: Sourced from report JSON `report.details[].name`.
+* `location_file`: Sourced from report JSON `report.details[].location.file`.
+* `location_line` (`NULLABLE`): Sourced from report JSON
+  `report.details[].location.line`.
+* `location_column` (`NULLABLE`): Sourced from report JSON
+  `report.details[].location.column`.
+* `browser` (`NULLABLE`): Can be one of `chrome`, `chromium`, `firefox`,
+  `webkit`, `safari` or `edge`, sourced from report JSON
+  `report.details[].browser`.
+* `github_codeowners` (`NULLABLE`): A comma-separated list sourced from report
+  JSON `report.details[].github.codeowners`.
+* `type` (`NULLABLE`) **[deprecated]**: Replaced by `taxonomy_type`. Sourced
+  from report JSON `report.details[].taxonomy.type`.
+* `taxonomy_type` (`NULLABLE`): Sourced from report JSON
+  `report.details[].taxonomy.type`.
+* `experience` (`NULLABLE`) **[deprecated]**: No longer part of the report
+  schema starting with v3. For v1/v2 reports this is sourced from the original
+  JSON at `report.details[].experience` before upgrade and injected onto the
+  outgoing record. Records without this dimension will appear once the source
+  reports are exclusively v3 or newer.
+* `tool` (`NULLABLE`) **[deprecated]**: Replaced by `taxonomy_tool`. Sourced
+  from report JSON `report.details[].taxonomy.tool`.
+* `taxonomy_tool` (`NULLABLE`): Sourced from report JSON
+  `report.details[].taxonomy.tool`.
+* `timeout` (`NULLABLE`) **[deprecated]**: Replaced by the `configuration_timeout`
+  measure. Stored as **milliseconds**, sourced from report JSON
+  `report.details[].configuration.timeout`.
+
+> [!WARNING]
+  Anything marked with **[deprecated]** should be moved away from. Sending of
+  this column will be removed in the near future.
+
+##### Removed
+
+* `location`: Starting with records that have `measure_name` of `report_v2` this
+  field will no longer be present. Please use `location_file` instead. If
+  wanting to get data from records prior to `report_v2` please use
+  `COALESCE(location, location_file)` to get a reasonable value.
+
+<!-- links -->
+[AWS Timestream]: https://aws.amazon.com/timestream
+[latest report schema]: https://github.com/Brightspace/test-reporting-node/tree/main/schemas/report
+[auto upgrading report construct]: https://github.com/Brightspace/test-reporting-node/blob/main/src/helpers/report.cjs

docs/report-submitter.md

@@ -0,0 +1,28 @@
+# Report Submitter
+
+## When to Use
+
+In most cases `ReportSubmitter` should not be used. To upload reports from Github use the [GitHub Action].
+It is used when the report needs to be uploaded outside of Github Actions.
+
+## Quick Start
+
+```js
+import { ReportBuilder }  from 'd2l-test-reporting/helpers/report-builder.js';
+import { ReportSubmitter } from 'd2l-test-reporting/helpers/report-submitter.js';
+
+const logger = {
+  info: (msg) => console.log(msg),
+  warning: (msg) => console.warn(msg),
+  error: (msg) => console.error(msg),
+  location: (msg, loc) => console.log(`${msg}: ${loc}`)
+};
+
+const report = new ReportBuilder('your-framework-name', logger);
+const submitter = new ReportSubmitter(logger); // AWS credentials are read from environment variables
+await submitter.submit(report);
+```
+
+
+<!-- links -->
+[GitHub Action]: https://github.com/Brightspace/test-reporting-action