Improve verify (#85)

* improves configurability of test results and aftTest behaviours and begins improvements to AftTest.verify calls
* moves handling of final result to _done function
* replaces calls to pass, pending and fail in run function with calls to _submitResult
* v11.2.0
* updates example project aft deps
* improving code and readme docs
* improves verify usage examples

README.md

@@ -11,6 +11,7 @@ describe('Sample Test', () => {
          * - for Jest use: `await aftJestTest(expect, () => doStuff());`
          * - for Mocha use: `await aftMochaTest(this, () => doStuff());`
          * - for Jasmine use: `await aftJasmineTest(() => doStuff());`
+         * - for ViTest use: `await aftVitestTest(ctx, () => doStuff());`
          */
         const aftJasmineTest(async (t: AftJasmineTest) => {
             const result: string = await feature.performActionAsync();
@@ -36,21 +37,19 @@ describe('Sample Test', () => {
          * - for Jest use: `await aftJestTest(expect, () => doStuff());`
          * - for Mocha use: `await aftMochaTest(this, () => doStuff());`
          * - for Jasmine use: `await aftJasmineTest(() => doStuff());`
+         * - for ViTest use: `await aftVitestTest(ctx, () => doStuff());`
          */
         await aftJasmineTest(async (v: AftJasmineTest) => {
             await v.reporter.step('creating instance of FeatureObj');
             const feature: FeatureObj = new FeatureObj();
-            const result = await v.verify(feature.isGood, true);
-            if (result.message) {
-                v.fail(result.message, 'C2345'); // reports failure result immediately
-            }
+            const result = await v.verify(feature.isGood, true, '[C2345] isGood returned not true'); // reports failure result immediately
             await v.reporter.step('about to call performAction');
             const result: string = await feature.performAction();
             await v.reporter.info(`result of performAction was '${result}'`);
             await v.reporter.trace('successfully executed expectation');
-            await v.verify(result, containing('result of action'));
+            await v.verify(result, containing('result of action'), '[C3344] performAction result mismatch'); // reports failure result immediately
         }, {
-            aftCfg: new AftConfig({logLevel: 'trace'}),
+            aftCfg: new AftConfig({logLevel: 'trace'}), // overrides `logLevel` used by other tests
             haltOnVerifyFailure: false, // continue if `verify` check fails
             onEventsMap: new Map<AftTestEvent, Array<AftTestFunction>>([
                 ['done', [() => performCleanup()]] // function run on completion
@@ -62,13 +61,15 @@ describe('Sample Test', () => {
 which would output the following logs:
 ```
 5:29:54 PM - [[C2345][C3344] can perform a more complex demonstration of AFT] - STEP  - 1: creating instance of FeatureObj
+5:29:55 PM - [[C2345][C3344] can perform a more complex demonstration of AFT] - PASS  - C2345
 5:29:55 PM - [[C2345][C3344] can perform a more complex demonstration of AFT] - STEP  - 2: about to call performAction
 5:29:55 PM - [[C2345][C3344] can perform a more complex demonstration of AFT] - INFO  - result of performAction was 'result of action'
 5:29:56 PM - [[C2345][C3344] can perform a more complex demonstration of AFT] - TRACE - successfully executed expectation
-5:29:56 PM - [[C2345][C3344] can perform a more complex demonstration of AFT] - PASS  - C2345
 5:29:56 PM - [[C2345][C3344] can perform a more complex demonstration of AFT] - PASS  - C3344
 ```
-> WARNING: Jasmine's _expect_ calls do not return a boolean as their type definitions would make you think and failed `expect` calls will only throw exceptions if the stop on failure option is enabled: 
+
+#### WARNING:
+> Jasmine's _expect_ calls do not return a boolean as their type definitions would make you think and failed `expect` calls will only throw exceptions if the stop on failure option is enabled: 
 ```typescript
 await aftTest(description, (t: AftTest) => {
     expect('foo').toBe('bar'); // fails but doesn't throw
@@ -79,10 +80,7 @@ await aftTest(description, (t: AftTest) => {
 }); // AFT will report as 'failed'
 
 await aftTest(description, (t: AftTest) => {
-    const result = await t.verify('foo', 'bar'); // fails but doesn't throw
-    if (result.message) {
-        await t.reporter.warn(result.message);
-    }
+    await t.verify('foo', 'bar'); // fails but doesn't throw
 }, { haltOnVerifyFailure = false }); // AFT will report as 'failed'
 ```
 
@@ -139,20 +137,22 @@ the purpose of a `PolicyPlugin` implementation is to provide execution control o
     "plugins": ["testrail-policy-plugin"]
 }
 ```
-> NOTE: if no plugin is specified then external Policy Engine integration will be disabled and _assertions_ will be executed without first checking that they should be run based on associated Test IDs
+#### NOTE:
+> if no plugin is specified then external Policy Engine integration will be disabled and _assertions_ will be executed without first checking that they should be run based on associated Test IDs
 
 ## Example Test Projects
-- [`selenium-jest`](./examples/selenium-jest/README.md) - demonstrates how to use the `SeleniumSession`, `SeleniumComponent`, `AftJestTest` and `AftJestReporter` within Jest tests
-- [`selenium-mocha`](./examples/selenium-mocha/README.md) - demonstrates how to use the `SeleniumSession`, `SeleniumComponent`, `AftMochaTest` and `AftMochaReporter` within Mocha tests
-- [`web-services-jasmine`](./examples/web-services-jasmine/README.md) - demonstrates how to use the `HttpService`, `AftJasmineTest` and `AftJasmineReporter` within Jasmine tests
-- [`webdriverio-mocha`](./examples/webdriverio-mocha/README.md) - demonstrates how to use the `WebdriverIoSession`, `WebdriverIoComponent`, `AftMochaTest` and `AftMochaReporter` within Mocha tests
+- [`cypress-mocha`](./examples/cypress-mocha/README.md) - demonstrates how to use the `AftMochaReporter`, with Cypress e2e tests (NOTE: Cypress tests run in a browser context so the `AftMochaTest` cannot be used as it relies on having a nodejs context)
+- [`selenium-jest`](./examples/selenium-jest/README.md) - demonstrates how to use the AFT `SeleniumSession`, `SeleniumComponent`, `AftJestTest` and `AftJestReporter` within Jest tests to verify Browser applications
+- [`selenium-mocha`](./examples/selenium-mocha/README.md) - demonstrates how to use the `SeleniumSession`, `SeleniumComponent`, `AftMochaTest` and `AftMochaReporter` within Mocha tests to verify Browser applications
+- [`web-services-jasmine`](./examples/web-services-jasmine/README.md) - demonstrates how to use the AFT `HttpService`, `AftJasmineTest` and `AftJasmineReporter` within Jasmine tests to test API endpoints
+- [`webdriverio-mocha`](./examples/webdriverio-mocha/README.md) - demonstrates how to use the `WebdriverIoSession`, `WebdriverIoComponent`, `AftMochaTest` and `AftMochaReporter` within Mocha tests to verify Browser and Mobile applications
 
 ## Contributing to AFT
 - create a Fork of the repo in GitHub
 - clone the code using `git clone https://github.com/<your-project-area>/automated-functional-testing automated-functional-testing` where `<your-project-area>` is replaced with the location of your Fork
 - run `npm install` to install all dependencies
 - run a build to ensure `npm workspaces` understands and caches the project layout using `npm run build`
-  - NOTE: you can build each project individually using `npm run build --workspace=<project-name>` where `<project-name>` is a value like `aft-core` or `aft-ui`
+  - **NOTE:** you can build each project individually using `npm run build --workspace=<project-name>` where `<project-name>` is a value like `aft-core` or `aft-ui`
 - run the tests using `npm run test` or individually using `npm run test --workspace=<project-name>`
 - when you are happy with your changes, submit a Pull Request back to the _main_ branch at https://github.com/bicarbon8/automated-functional-testing