docs: support optional methods (#13415)

So far, these are used in `Reporter`.

docs/src/test-reporter-api/class-reporter.md

@@ -89,7 +89,7 @@ Here is a typical order of reporter calls:
 Additionally, [`method: Reporter.onStdOut`] and [`method: Reporter.onStdErr`] are called when standard output is produced in the worker process, possibly during a test execution,
 and [`method: Reporter.onError`] is called when something went wrong outside of the test execution.
 
-## method: Reporter.onBegin
+## optional method: Reporter.onBegin
 
 Called once before running tests. All tests have been already discovered and put into a hierarchy of [Suite]s.
 
@@ -105,7 +105,7 @@ The root suite that contains all projects, files and test cases.
 
 
 
-## async method: Reporter.onEnd
+## optional async method: Reporter.onEnd
 
 Called after all tests has been run, or testing has been interrupted. Note that this method may return a [Promise] and Playwright Test will await it.
 
@@ -122,7 +122,7 @@ Result of the full test run.
 
 
 
-## method: Reporter.onError
+## optional method: Reporter.onError
 
 Called on some global error, for example unhandled exception in the worker process.
 
@@ -132,7 +132,7 @@ Called on some global error, for example unhandled exception in the worker proce
 The error.
 
 
-## method: Reporter.onStdErr
+## optional method: Reporter.onStdErr
 
 Called when something has been written to the standard error in the worker process.
 
@@ -152,7 +152,7 @@ Test that was running. Note that output may happen when no test is running, in w
 Result of the test run, this object gets populated while the test runs.
 
 
-## method: Reporter.onStdOut
+## optional method: Reporter.onStdOut
 
 Called when something has been written to the standard output in the worker process.
 
@@ -171,7 +171,7 @@ Test that was running. Note that output may happen when no test is running, in w
 
 Result of the test run, this object gets populated while the test runs.
 
-## method: Reporter.onStepBegin
+## optional method: Reporter.onStepBegin
 
 Called when a test step started in the worker process.
 
@@ -190,7 +190,7 @@ Result of the test run, this object gets populated while the test runs.
 
 Test step instance that has started.
 
-## method: Reporter.onStepEnd
+## optional method: Reporter.onStepEnd
 
 Called when a test step finished in the worker process.
 
@@ -209,7 +209,7 @@ Result of the test run.
 
 Test step instance that has finished.
 
-## method: Reporter.onTestBegin
+## optional method: Reporter.onTestBegin
 
 Called after a test has been started in the worker process.
 
@@ -224,7 +224,7 @@ Test that has been started.
 Result of the test run, this object gets populated while the test runs.
 
 
-## method: Reporter.onTestEnd
+## optional method: Reporter.onTestEnd
 
 Called after a test has been finished in the worker process.
 
@@ -239,7 +239,7 @@ Test that has been finished.
 Result of the test run.
 
 
-## method: Reporter.printsToStdio
+## optional method: Reporter.printsToStdio
 - returns: <[boolean]>
 
 Whether this reporter uses stdio for reporting. When it does not, Playwright Test could add some output to enhance user experience.

packages/playwright-test/types/testReporter.d.ts

@@ -355,62 +355,12 @@ export interface FullResult {
  * went wrong outside of the test execution.
  */
 export interface Reporter {
-  /**
-   * Whether this reporter uses stdio for reporting. When it does not, Playwright Test could add some output to enhance user
-   * experience.
-   */
-  printsToStdio?(): boolean;
   /**
    * Called once before running tests. All tests have been already discovered and put into a hierarchy of [Suite]s.
    * @param config Resolved configuration.
    * @param suite The root suite that contains all projects, files and test cases.
    */
   onBegin?(config: FullConfig, suite: Suite): void;
-  /**
-   * Called after a test has been started in the worker process.
-   * @param test Test that has been started.
-   * @param result Result of the test run, this object gets populated while the test runs.
-   */
-  onTestBegin?(test: TestCase, result: TestResult): void;
-  /**
-   * Called when something has been written to the standard output in the worker process.
-   * @param chunk Output chunk.
-   * @param test Test that was running. Note that output may happen when no test is running, in which case this will be [void].
-   * @param result Result of the test run, this object gets populated while the test runs.
-   */
-  onStdOut?(chunk: string | Buffer, test?: TestCase, result?: TestResult): void;
-  /**
-   * Called when something has been written to the standard error in the worker process.
-   * @param chunk Output chunk.
-   * @param test Test that was running. Note that output may happen when no test is running, in which case this will be [void].
-   * @param result Result of the test run, this object gets populated while the test runs.
-   */
-  onStdErr?(chunk: string | Buffer, test?: TestCase, result?: TestResult): void;
-  /**
-   * Called after a test has been finished in the worker process.
-   * @param test Test that has been finished.
-   * @param result Result of the test run.
-   */
-  onTestEnd?(test: TestCase, result: TestResult): void;
-  /**
-   * Called when a test step started in the worker process.
-   * @param test Test that the step belongs to.
-   * @param result Result of the test run, this object gets populated while the test runs.
-   * @param step Test step instance that has started.
-   */
-  onStepBegin?(test: TestCase, result: TestResult, step: TestStep): void;
-  /**
-   * Called when a test step finished in the worker process.
-   * @param test Test that the step belongs to.
-   * @param result Result of the test run.
-   * @param step Test step instance that has finished.
-   */
-  onStepEnd?(test: TestCase, result: TestResult, step: TestStep): void;
-  /**
-   * Called on some global error, for example unhandled exception in the worker process.
-   * @param error The error.
-   */
-  onError?(error: TestError): void;
   /**
    * Called after all tests has been run, or testing has been interrupted. Note that this method may return a [Promise] and
    * Playwright Test will await it.
@@ -422,7 +372,63 @@ export interface Reporter {
    * - `'interrupted'` - Interrupted by the user.
    */
   onEnd?(result: FullResult): void | Promise<void>;
-}
+  /**
+   * Called on some global error, for example unhandled exception in the worker process.
+   * @param error The error.
+   */
+  onError?(error: TestError): void;
+
+  /**
+   * Called when something has been written to the standard error in the worker process.
+   * @param chunk Output chunk.
+   * @param test Test that was running. Note that output may happen when no test is running, in which case this will be [void].
+   * @param result Result of the test run, this object gets populated while the test runs.
+   */
+  onStdErr?(chunk: string|Buffer, test: void|TestCase, result: void|TestResult): void;
+
+  /**
+   * Called when something has been written to the standard output in the worker process.
+   * @param chunk Output chunk.
+   * @param test Test that was running. Note that output may happen when no test is running, in which case this will be [void].
+   * @param result Result of the test run, this object gets populated while the test runs.
+   */
+  onStdOut?(chunk: string|Buffer, test: void|TestCase, result: void|TestResult): void;
+
+  /**
+   * Called when a test step started in the worker process.
+   * @param test Test that the step belongs to.
+   * @param result Result of the test run, this object gets populated while the test runs.
+   * @param step Test step instance that has started.
+   */
+  onStepBegin?(test: TestCase, result: TestResult, step: TestStep): void;
+
+  /**
+   * Called when a test step finished in the worker process.
+   * @param test Test that the step belongs to.
+   * @param result Result of the test run.
+   * @param step Test step instance that has finished.
+   */
+  onStepEnd?(test: TestCase, result: TestResult, step: TestStep): void;
+
+  /**
+   * Called after a test has been started in the worker process.
+   * @param test Test that has been started.
+   * @param result Result of the test run, this object gets populated while the test runs.
+   */
+  onTestBegin?(test: TestCase, result: TestResult): void;
+
+  /**
+   * Called after a test has been finished in the worker process.
+   * @param test Test that has been finished.
+   * @param result Result of the test run.
+   */
+  onTestEnd?(test: TestCase, result: TestResult): void;
+
+  /**
+   * Whether this reporter uses stdio for reporting. When it does not, Playwright Test could add some output to enhance user
+   * experience.
+   */
+  printsToStdio?(): boolean;}
 
 // This is required to not export everything by default. See https://github.com/Microsoft/TypeScript/issues/19545#issuecomment-340490459
 export {};

utils/doclint/api_parser.js

@@ -83,7 +83,7 @@ class ApiParser {
    * @param {MarkdownNode} spec
    */
   parseMember(spec) {
-    const match = spec.text.match(/(event|method|property|async method): ([^.]+)\.(.*)/);
+    const match = spec.text.match(/(event|method|property|async method|optional method|optional async method): ([^.]+)\.(.*)/);
     if (!match)
       throw new Error('Invalid member: ' + spec.text);
     const name = match[3];
@@ -105,10 +105,12 @@ class ApiParser {
       member = Documentation.Member.createEvent(extractLangs(spec), name, returnType, comments);
     if (match[1] === 'property')
       member = Documentation.Member.createProperty(extractLangs(spec), name, returnType, comments, !optional);
-    if (match[1] === 'method' || match[1] === 'async method') {
+    if (['method', 'async method', 'optional method', 'optional async method'].includes(match[1])) {
       member = Documentation.Member.createMethod(extractLangs(spec), name, [], returnType, comments);
-      if (match[1] === 'async method')
+      if (match[1].includes('async'))
         member.async = true;
+      if (match[1].includes('optional'))
+        member.required = false;
     }
     const clazz = this.classes.get(match[2]);
     const existingMember = clazz.membersArray.find(m => m.name === name && m.kind === member.kind);

utils/doclint/documentation.js

@@ -285,9 +285,8 @@ Documentation.Member = class {
    * @param {!Array<!Documentation.Member>} argsArray
    * @param {MarkdownNode[]=} spec
    * @param {boolean=} required
-   * @param {string[]=} templates
    */
-  constructor(kind, langs, name, type, argsArray, spec = undefined, required = true, templates = []) {
+  constructor(kind, langs, name, type, argsArray, spec = undefined, required = true) {
     this.kind = kind;
     this.langs = langs;
     this.name = name;

utils/generate_types/overrides-testReporter.d.ts

@@ -44,15 +44,7 @@ export interface FullResult {
 }
 
 export interface Reporter {
-  printsToStdio?(): boolean;
   onBegin?(config: FullConfig, suite: Suite): void;
-  onTestBegin?(test: TestCase, result: TestResult): void;
-  onStdOut?(chunk: string | Buffer, test?: TestCase, result?: TestResult): void;
-  onStdErr?(chunk: string | Buffer, test?: TestCase, result?: TestResult): void;
-  onTestEnd?(test: TestCase, result: TestResult): void;
-  onStepBegin?(test: TestCase, result: TestResult, step: TestStep): void;
-  onStepEnd?(test: TestCase, result: TestResult, step: TestStep): void;
-  onError?(error: TestError): void;
   onEnd?(result: FullResult): void | Promise<void>;
 }