From 545d79395675c12a45ee55756a0125ad8ab5d5ec Mon Sep 17 00:00:00 2001
From: Dmitry Gozman <dgozman@gmail.com>
Date: Wed, 15 Sep 2021 15:29:06 -0700
Subject: [PATCH] docs: an overview of reporter methods (#8948)

---
 docs/src/test-reporter-api/class-reporter.md | 12 ++++++++--
 types/testReporter.d.ts                      | 25 +++++++++++++++++++-
 2 files changed, 34 insertions(+), 3 deletions(-)

diff --git a/docs/src/test-reporter-api/class-reporter.md b/docs/src/test-reporter-api/class-reporter.md
index 29482fac84..4fa27a5d20 100644
--- a/docs/src/test-reporter-api/class-reporter.md
+++ b/docs/src/test-reporter-api/class-reporter.md
@@ -55,7 +55,7 @@ class MyReporter implements Reporter {
 export default MyReporter;
 ```
 
-Now use this reporter with [`property: TestConfig.reporter`].
+Now use this reporter with [`property: TestConfig.reporter`]. Learn more about [using reporters](./test-reporters.md).
 
 ```js js-flavor=js
 // playwright.config.js
@@ -79,7 +79,15 @@ const config: PlaywrightTestConfig = {
 export default config;
 ```
 
-Learn more about [reporters](./test-reporters.md).
+Here is a typical order of reporter calls:
+* [`method: Reporter.onBegin`] is called once with a root suite that contains all other suites and tests. Learn more about [suites hierarchy][Suite].
+* [`method: Reporter.onTestBegin`] is called for each test run. It is given a [TestCase] that is executed, and a [TestResult] that is almost empty. Test result will be populated while the test runs (for example, with steps and stdio) and will get final `status` once the test finishes.
+* [`method: Reporter.onStepBegin`] and [`method: Reporter.onStepEnd`] are called for each executed step inside the test. When steps are executed, test run has not finished yet.
+* [`method: Reporter.onTestEnd`] is called when test run has finished. By this time, [TestResult] is complete and you can use [`property: TestResult.status`], [`property: TestResult.error`] and more.
+* [`method: Reporter.onEnd`] is called once after all tests that should run had finished.
+
+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
 
diff --git a/types/testReporter.d.ts b/types/testReporter.d.ts
index 8f2b6c9344..4503bf6eb8 100644
--- a/types/testReporter.d.ts
+++ b/types/testReporter.d.ts
@@ -306,6 +306,7 @@ export interface FullResult {
  * ```
  *
  * Now use this reporter with [testConfig.reporter](https://playwright.dev/docs/api/class-testconfig#test-config-reporter).
+ * Learn more about [using reporters](https://playwright.dev/docs/test-reporters).
  *
  * ```ts
  * // playwright.config.ts
@@ -317,7 +318,29 @@ export interface FullResult {
  * export default config;
  * ```
  *
- * Learn more about [reporters](https://playwright.dev/docs/test-reporters).
+ * Here is a typical order of reporter calls:
+ * - [reporter.onBegin(config, suite)](https://playwright.dev/docs/api/class-reporter#reporter-on-begin) is called once
+ *   with a root suite that contains all other suites and tests. Learn more about [suites hierarchy][Suite].
+ * - [reporter.onTestBegin(test, result)](https://playwright.dev/docs/api/class-reporter#reporter-on-test-begin) is
+ *   called for each test run. It is given a [TestCase] that is executed, and a [TestResult] that is almost empty. Test
+ *   result will be populated while the test runs (for example, with steps and stdio) and will get final `status` once
+ *   the test finishes.
+ * - [reporter.onStepBegin(test, result, step)](https://playwright.dev/docs/api/class-reporter#reporter-on-step-begin)
+ *   and [reporter.onStepEnd(test, result, step)](https://playwright.dev/docs/api/class-reporter#reporter-on-step-end)
+ *   are called for each executed step inside the test. When steps are executed, test run has not finished yet.
+ * - [reporter.onTestEnd(test, result)](https://playwright.dev/docs/api/class-reporter#reporter-on-test-end) is called
+ *   when test run has finished. By this time, [TestResult] is complete and you can use
+ *   [testResult.status](https://playwright.dev/docs/api/class-testresult#test-result-status),
+ *   [testResult.error](https://playwright.dev/docs/api/class-testresult#test-result-error) and more.
+ * - [reporter.onEnd(result)](https://playwright.dev/docs/api/class-reporter#reporter-on-end) is called once after all
+ *   tests that should run had finished.
+ *
+ * Additionally,
+ * [reporter.onStdOut(chunk, test, result)](https://playwright.dev/docs/api/class-reporter#reporter-on-std-out) and
+ * [reporter.onStdErr(chunk, test, result)](https://playwright.dev/docs/api/class-reporter#reporter-on-std-err) are called
+ * when standard output is produced in the worker process, possibly during a test execution, and
+ * [reporter.onError(error)](https://playwright.dev/docs/api/class-reporter#reporter-on-error) is called when something
+ * went wrong outside of the test execution.
  */
 export interface Reporter {
   /**