fix: fixed PW_TEST_HTML_REPORT_OPEN + more type safe + doc (#24571)

Co-authored-by: Max Schmitt <max@schmitt.mx>

docs/src/test-reporters-js.md

@@ -157,7 +157,7 @@ npx playwright test --reporter=html
 ```
 
 By default, HTML report is opened automatically if some of the tests failed. You can control this behavior via the
-`open` property in the Playwright config. The possible values for that property are `always`, `never` and `on-failure`
+`open` property in the Playwright config or the `PW_TEST_HTML_REPORT_OPEN` environmental variable. The possible values for that property are `always`, `never` and `on-failure`
 (default).
 
 You can also configure `host` and `port` that are used to serve the HTML report.

packages/playwright-test/src/reporters/html.ts

@@ -40,7 +40,14 @@ type TestEntry = {
   testCaseSummary: TestCaseSummary
 };
 
-type HtmlReportOpenOption = 'always' | 'never' | 'on-failure';
+
+const htmlReportOptions = ['always', 'never', 'on-failure'];
+type HtmlReportOpenOption = (typeof htmlReportOptions)[number];
+
+const isHtmlReportOption = (type: string): type is HtmlReportOpenOption => {
+  return htmlReportOptions.includes(type);
+};
+
 type HtmlReporterOptions = {
   configDir: string,
   outputFolder?: string,
@@ -100,7 +107,7 @@ class HtmlReporter extends EmptyReporter {
     const outputFolder = reportFolderFromEnv() ?? resolveReporterOutputPath('playwright-report', this._options.configDir, this._options.outputFolder);
     return {
       outputFolder,
-      open: process.env.PW_TEST_HTML_REPORT_OPEN as any || this._options.open || 'on-failure',
+      open: getHtmlReportOptionProcessEnv() || this._options.open || 'on-failure',
       attachmentsBaseURL: this._options.attachmentsBaseURL || 'data/'
     };
   }
@@ -137,6 +144,18 @@ function reportFolderFromEnv(): string | undefined {
   return undefined;
 }
 
+function getHtmlReportOptionProcessEnv(): HtmlReportOpenOption | undefined {
+  const processKey = 'PW_TEST_HTML_REPORT_OPEN';
+  const htmlOpenEnv = process.env[processKey];
+  if (!htmlOpenEnv)
+    return undefined;
+  if (!isHtmlReportOption(htmlOpenEnv)) {
+    console.log(colors.red(`Configuration Error: HTML reporter Invalid value for ${processKey}: ${htmlOpenEnv}. Valid values are: ${htmlReportOptions.join(', ')}`));
+    return undefined;
+  }
+  return htmlOpenEnv;
+}
+
 function standaloneDefaultFolder(): string {
   return reportFolderFromEnv() ?? resolveReporterOutputPath('playwright-report', process.cwd(), undefined);
 }

tests/playwright-test/reporter-html.spec.ts

@@ -86,6 +86,23 @@ for (const useIntermediateMergeReport of [false, true] as const) {
     });
 
 
+    test('should not throw when PW_TEST_HTML_REPORT_OPEN value is invalid', async ({ runInlineTest, page, showReport }, testInfo) => {
+      const invalidOption = 'invalid-option';
+      const result = await runInlineTest({
+        'playwright.config.ts': `
+          module.exports = { preserveOutput: 'failures-only' };
+        `,
+        'a.test.js': `
+          import { test, expect } from '@playwright/test';
+          test('passes', async ({ page }, testInfo) => {
+            expect(2).toEqual(2);
+          });
+        `,
+      }, { reporter: 'dot,html' }, { PW_TEST_HTML_REPORT_OPEN: invalidOption });
+      expect(result.exitCode).toBe(0);
+      expect(result.passed).toBe(1);
+    });
+
     test('should not throw when attachment is missing', async ({ runInlineTest, page, showReport }, testInfo) => {
       const result = await runInlineTest({
         'playwright.config.ts': `