improve docs on spec related retries - closes #7603

examples/wdio.conf.js

@@ -274,7 +274,9 @@ exports.config = {
     afterHook: function (test, context, { error, result, duration, passed, retries }) {
     },
     /**
-     * Function to be executed before a test (in Mocha/Jasmine) starts.
+     * Function to be executed before a test (in Mocha/Jasmine only)
+     * @param {Object} test    test object
+     * @param {Object} context scope object the test was executed with
      */
     beforeTest: function (test, context) {
     },
@@ -296,7 +298,14 @@ exports.config = {
     afterCommand: function (commandName, args, result, error) {
     },
     /**
-     * Function to be executed after a test (in Mocha/Jasmine) ends.
+     * Function to be executed after a test (in Mocha/Jasmine only)
+     * @param {Object}  test             test object
+     * @param {Object}  context          scope object the test was executed with
+     * @param {Error}   result.error     error object in case the test fails, otherwise `undefined`
+     * @param {Any}     result.result    return object of test function
+     * @param {Number}  result.duration  duration of test
+     * @param {Boolean} result.passed    true if test has passed, otherwise false
+     * @param {Object}  result.retries   informations to spec related retries, e.g. `{ attempts: 0, limit: 0 }`
      */
     afterTest: function (test, context, { error, result, duration, passed, retries }) {
     },

packages/wdio-cli/src/templates/afterTest.ejs

@@ -1,5 +1,12 @@
 /**
-     * Function to be executed after a test (in Mocha/Jasmine).
+     * Function to be executed after a test (in Mocha/Jasmine only)
+     * @param {Object}  test             test object
+     * @param {Object}  context          scope object the test was executed with
+     * @param {Error}   result.error     error object in case the test fails, otherwise `undefined`
+     * @param {Any}     result.result    return object of test function
+     * @param {Number}  result.duration  duration of test
+     * @param {Boolean} result.passed    true if test has passed, otherwise false
+     * @param {Object}  result.retries   informations to spec related retries, e.g. `{ attempts: 0, limit: 0 }`
      */<%
 if (reporters.length && reporters.includes('allure')) {%>
     afterTest: async function(test, context, { error, result, duration, passed, retries }) {

packages/wdio-types/src/Services.ts

@@ -179,17 +179,21 @@ export interface HookFunctions {
     beforeSuite?(suite: Suite): void;
 
     /**
-     * Function to be executed before a test (in Mocha/Jasmine) starts.
-     * @param test      details to current running test (represents step in Cucumber)
-     * @param context   context to current running test (represents World object in Cucumber)
+     * Function to be executed before a test (in Mocha/Jasmine only)
+     * @param {Object} test    test object
+     * @param {Object} context scope object the test was executed with
      */
     beforeTest?(test: Test, context: any): void;
 
     /**
-     * Function to be executed after a test (in Mocha/Jasmine) ends.
-     * @param test      details to current running test (represents step in Cucumber)
-     * @param context   context to current running test (represents World object in Cucumber)
-     * @param result    test result
+     * Function to be executed after a test (in Mocha/Jasmine only)
+     * @param {Object}  test             test object
+     * @param {Object}  context          scope object the test was executed with
+     * @param {Error}   result.error     error object in case the test fails, otherwise `undefined`
+     * @param {Any}     result.result    return object of test function
+     * @param {Number}  result.duration  duration of test
+     * @param {Boolean} result.passed    true if test has passed, otherwise false
+     * @param {Object}  result.retries   informations to spec related retries, e.g. `{ attempts: 0, limit: 0 }`
      */
     afterTest?(test: Test, context: any, result: TestResult): void;
 

website/docs/ConfigurationFile.md

@@ -352,7 +352,9 @@ exports.config = {
     afterHook: function (test, context, { error, result, duration, passed, retries }) {
     },
     /**
-     * Function to be executed before a test (in Mocha/Jasmine) starts.
+     * Function to be executed before a test (in Mocha/Jasmine only)
+     * @param {Object} test    test object
+     * @param {Object} context scope object the test was executed with
      */
     beforeTest: function (test, context) {
     },
@@ -373,7 +375,14 @@ exports.config = {
     afterCommand: function (commandName, args, result, error) {
     },
     /**
-     * Function to be executed after a test (in Mocha/Jasmine)
+     * Function to be executed after a test (in Mocha/Jasmine only)
+     * @param {Object}  test             test object
+     * @param {Object}  context          scope object the test was executed with
+     * @param {Error}   result.error     error object in case the test fails, otherwise `undefined`
+     * @param {Any}     result.result    return object of test function
+     * @param {Number}  result.duration  duration of test
+     * @param {Boolean} result.passed    true if test has passed, otherwise false
+     * @param {Object}  result.retries   informations to spec related retries, e.g. `{ attempts: 0, limit: 0 }`
      */
     afterTest: function (test, context, { error, result, duration, passed, retries }) {
     },

website/docs/Options.md

@@ -413,11 +413,11 @@ Parameters:
 
 ### beforeTest
 
-Function to be executed before a test (in Mocha/Jasmine) starts.
+Function to be executed before a test (in Mocha/Jasmine only).
 
 Parameters:
 - `test` (`object`): test details
-- `context` (`object`): test context
+- `context` (`object`): scope object the test was executed with
 
 ### beforeCommand
 
@@ -443,7 +443,12 @@ Function to be executed after a test (in Mocha/Jasmine) ends.
 
 Parameters:
 - `test` (`object`): test details
-- `context` (`object`): test context
+- `context` (`object`): scope object the test was executed with
+- `result.error` (`Error`): error object in case the test fails, otherwise `undefined`
+- `result.result` (`Any`): return object of test function
+- `result.duration` (`Number`): duration of test
+- `result.passed` (`Boolean`): true if test has passed, otherwise false
+- `result.retries` (`Object`): informations to spec related retries, e.g. `{ attempts: 0, limit: 0 }`
 - `result` (`object`): hook result (contains `error`, `result`, `duration`, `passed`, `retries` properties)
 
 ### afterSuite

website/docs/Retry.md

@@ -107,7 +107,7 @@ If you are using Jasmine, the second parameter is reserved for timeout. To apply
 </TabItem>
 </Tabs>
 
-This retry mechanism only allows to retry single hooks or test blocks. If your test is accompanied with a hook to set up your application, this hook is not being run. [Mocha offers](https://mochajs.org/#retry-tests) native test retries that provide this behavior while Jasmine doesn't.
+This retry mechanism only allows to retry single hooks or test blocks. If your test is accompanied with a hook to set up your application, this hook is not being run. [Mocha offers](https://mochajs.org/#retry-tests) native test retries that provide this behavior while Jasmine doesn't. You can access the number of executed retries in the `afterTest` hook.
 
 ## Rerunning in Cucumber