reporting-labs 0.6.7 → 0.6.8

package/README.md

@@ -303,7 +303,10 @@ Every option is optional. `npx reporting-labs init` writes them all, with commen
 | `title` | `'Test report'` | Title in the header |
 | `logo` | – | Your logo next to the title: `'logo.png'` (a file next to the config, embedded in the report) or an https URL |
 | `project` | – | `{ name, version, team, url }` shown under the title |
-| `metadata` | `{}` | Chips in the header, e.g. `{ env: 'staging', build: '#1842' }`. `build` labels the run in the trend; in CI the run number is used when it is not set |
+| `metadata` | `{}` | Chips in the header, e.g. `{ env: 'staging', build: '#1842' }`. `build` labels the run in the trend; in CI the run number is used when it is not set. The environment name is also read from the process environment and wins over `env` here: `ENV`, `TEST_ENV`, `APP_ENV`, `TARGET_ENV` and friends, or any variable ending in `_ENV` / `_ENVIRONMENT` (`OPENCART_ENV`), so a config that says `local` still labels CI reports `dev`, `qa`, `stage` |
+| `envVar` | – | Name of the variable that holds the environment name, when the detection cannot guess it |
+
+**Runtime overrides.** `REPORTING_LABS_METADATA_<KEY>` sets a header chip from the environment (`REPORTING_LABS_METADATA_ENV=qa`, `REPORTING_LABS_METADATA_RELEASE=2.3`) and `REPORTING_LABS_TITLE`, `_THEME`, `_PALETTE`, `_ACCENT`, `_LOGO` the matching option; they win over the config. The env chip resolves in this order: `REPORTING_LABS_METADATA_ENV`, the variable `envVar` names, the conventional names (`ENV`, `TEST_ENV`, `APP_ENV`, `TARGET_ENV`, `CI_ENVIRONMENT_NAME`, anything ending in `_ENV`), then `metadata.env` in the config.
 | `env` | – | Extra rows on the Environment card |
 | `links` | `{}` | Turn meta keys into links. `{id}` is replaced by the value. An object `{ url, display }` builds the URL from several fields of an object passed to `meta()`, see below |
 | `maskKeys` | `[]` | Extra keys to mask as `****` |

package/dist/reporter.d.ts

@@ -54,3 +54,10 @@ export default class ReportingLabsReporter implements Reporter {
     private serializeStep;
     private serializeAttachment;
 }
+/**
+ * The environment name the run was pointed at, from the process environment: the variable named
+ * by `envVar` if given, else the usual names (ENV, TEST_ENV, APP_ENV, TARGET_ENV, …), else any
+ * variable whose name ends in _ENV or _ENVIRONMENT (OPENCART_ENV, app_env). Every project names
+ * it differently; this finds it without being told. Undefined when nothing fits.
+ */
+export declare function detectEnvName(env: NodeJS.ProcessEnv, envVar?: string): string | undefined;

package/dist/reporter.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectEnvName = detectEnvName;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
@@ -56,7 +57,32 @@ class ReportingLabsReporter {
         this.masker = (0, mask_1.makeMasker)();
         this.globalErrors = [];
         this.globalOutput = [];
-        this.options = options;
+        // The env chip. A runtime variable beats the config file, the same precedence as everything
+        // else: the ENV / TEST_ENV / ENVIRONMENT / APP_ENV a CI job exports wins over metadata.env in
+        // the config, so a config that says env: 'local' still labels the pipeline's reports dev, qa,
+        // stage without anyone touching it. The config value applies when no variable is set.
+        // Runtime overrides, highest precedence: REPORTING_LABS_METADATA_<KEY> sets a header chip
+        // (REPORTING_LABS_METADATA_ENV=qa, REPORTING_LABS_METADATA_RELEASE=2.3) and REPORTING_LABS_TITLE /
+        // _THEME / _PALETTE / _ACCENT / _LOGO the matching option, so a pipeline can label a run without
+        // touching the config. Same contract as the Java reporter's REPORTING_LABS_* variables.
+        const metadata = { ...(options.metadata ?? {}) };
+        for (const [k, v] of Object.entries(process.env)) {
+            const m = /^REPORTING_LABS_METADATA_([A-Z0-9_]+)$/.exec(k);
+            if (m && v && v.trim())
+                metadata[m[1].toLowerCase()] = v.trim();
+        }
+        // Below the explicit override, the environment name the run was pointed at, found by convention
+        // (ENV, TEST_ENV, APP_ENV, TARGET_ENV, anything ending in _ENV) or the variable `envVar` names.
+        // It beats metadata.env in the config: a runtime value wins over the file, as everywhere else.
+        if (!process.env.REPORTING_LABS_METADATA_ENV) {
+            const detected = detectEnvName(process.env, options.envVar);
+            if (detected)
+                metadata.env = detected;
+        }
+        const scalar = (name, current) => { const v = process.env['REPORTING_LABS_' + name]; return v && v.trim() ? v.trim() : current; };
+        this.options = { ...options, metadata,
+            title: scalar('TITLE', options.title), theme: scalar('THEME', options.theme), palette: scalar('PALETTE', options.palette),
+            accent: scalar('ACCENT', options.accent), logo: scalar('LOGO', options.logo) };
         this.masker = (0, mask_1.makeMasker)(options.maskKeys ?? [], { knownValues: options.maskValues ?? [], fromEnv: options.maskFromEnv !== false });
     }
     printsToStdio() { return false; }
@@ -595,6 +621,35 @@ class ReportingLabsReporter {
 }
 exports.default = ReportingLabsReporter;
 /** Run number from the CI system, used to label history entries when metadata.build is not set. */
+/** Variables whose name ends in ENV but never hold an environment name. */
+const NOT_AN_ENV_VAR = new Set(['GITHUB_ENV', 'NODE_ENV', 'BASH_ENV', 'VIRTUAL_ENV', 'CONDA_DEFAULT_ENV', 'RUNNER_ENVIRONMENT', 'PIPENV_ACTIVE', 'ZSH_ENV', 'JAVA_ENV', 'DOTNET_ENVIRONMENT', 'ASPNETCORE_ENVIRONMENT', 'HOSTING_ENVIRONMENT']);
+/** Names every project seems to pick first, in order. */
+const ENV_VAR_NAMES = ['ENV', 'TEST_ENV', 'ENVIRONMENT', 'APP_ENV', 'TARGET_ENV', 'RUN_ENV', 'DEPLOY_ENV', 'ENV_NAME', 'TEST_ENVIRONMENT', 'TARGET_ENVIRONMENT', 'CI_ENVIRONMENT_NAME', 'DEPLOYMENT_ENVIRONMENT', 'STAGE'];
+/** dev, qa, stage-2, app_qa, prod-eu: a short token, never a path, URL or sentence. */
+const looksLikeEnvName = (v) => !!v && /^[A-Za-z][\w.-]{0,31}$/.test(v.trim());
+/**
+ * The environment name the run was pointed at, from the process environment: the variable named
+ * by `envVar` if given, else the usual names (ENV, TEST_ENV, APP_ENV, TARGET_ENV, …), else any
+ * variable whose name ends in _ENV or _ENVIRONMENT (OPENCART_ENV, app_env). Every project names
+ * it differently; this finds it without being told. Undefined when nothing fits.
+ */
+function detectEnvName(env, envVar) {
+    const get = (name) => { const v = env[name] ?? env[name.toLowerCase()]; return looksLikeEnvName(v) ? v.trim() : undefined; };
+    if (envVar)
+        return get(envVar) ?? (looksLikeEnvName(env[envVar]) ? env[envVar].trim() : undefined);
+    for (const n of ENV_VAR_NAMES) {
+        const v = get(n);
+        if (v)
+            return v;
+    }
+    const wild = Object.keys(env).filter(k => /_(ENV|ENVIRONMENT|ENV_NAME)$/i.test(k) && !NOT_AN_ENV_VAR.has(k.toUpperCase())).sort();
+    for (const k of wild) {
+        const v = env[k];
+        if (looksLikeEnvName(v))
+            return v.trim();
+    }
+    return undefined;
+}
 function ciRunLabel(env) {
     const n = env.GITHUB_RUN_NUMBER || env.BUILD_NUMBER || env.CI_PIPELINE_IID || env.CIRCLE_BUILD_NUM || env.BUILD_BUILDNUMBER || env.BITBUCKET_BUILD_NUMBER;
     return n ? `#${n}` : undefined;

package/dist/types.d.ts

@@ -25,6 +25,8 @@ export interface ReportingLabsOptions {
     embedVideos?: boolean;
     /** Key/value shown in the header (env, branch, build...). `build` labels the run in the history; when it is not set the CI run number is used. */
     metadata?: Record<string, string>;
+    /** Name of the environment variable that holds the environment name, when it is not one the reporter finds by itself (ENV, TEST_ENV, APP_ENV, anything ending in _ENV). */
+    envVar?: string;
     /** Extra sections rendered below the summary. HTML is allowed. */
     sections?: Array<{
         title: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reporting-labs",
-  "version": "0.6.7",
+  "version": "0.6.8",
   "description": "reportingLabs – beautiful, customizable single-file HTML test reports. One line of config. Playwright adapter included, more runners on the way.",
   "keywords": [
     "test-report",