add instructions for cucumber plugin

.gitignore

@@ -6,3 +6,4 @@
 node_modules
 /tests/Cypress/cypress/videos
 /tests/Cypress/cypress/screenshots
+/tests/Cypress/cucumber-report.html

README.md

@@ -10,6 +10,27 @@ This integration helps you to automatically send test results to TestRail. And y
 
 Add your TestRail credentials in Cypress, decide which test results should be sent to TestRail and you're done!
 
+<!-- TOC -->
+  * [1. Installation](#1-installation)
+    * [1.1 Pre-Requisites](#11-pre-requisites)
+  * [2. Setup Wizard](#2-setup-wizard)
+  * [3. Execution Modes](#3-execution-modes)
+    * [3.1 Mode A: Send results to one or more runs in TestRail](#31-mode-a-send-results-to-one-or-more-runs-in-testrail)
+    * [3.2 Mode B: Create new Run in TestRail for every Cypress run](#32-mode-b-create-new-run-in-testrail-for-every-cypress-run)
+  * [4. Register Plugin](#4-register-plugin)
+    * [4.1 (Optional) Register plugin for using Cypress in Open Mode](#41-optional-register-plugin-for-using-cypress-in-open-mode)
+  * [5. Map Test Cases](#5-map-test-cases)
+  * [6. Advanced Features](#6-advanced-features)
+    * [6.1 Sending Screenshots on failures](#61-sending-screenshots-on-failures)
+  * [7. Variables](#7-variables)
+    * [7.1 Use on CLI](#71-use-on-cli)
+    * [7.2 Use in cypress.env.json](#72-use-in-cypressenvjson)
+  * [8. Using multiple Cypress plugins](#8-using-multiple-cypress-plugins)
+  * [9. Cucumber Gherkin Support](#9-cucumber-gherkin-support)
+    * [9.1 Installation](#91-installation)
+  * [10. Copying / License](#10-copying--license)
+<!-- TOC -->
+
 ### 1. Installation
 
 ```ruby 
@@ -204,15 +225,15 @@ Examples on how to use it are below the list.
 | CYPRESS_TESTRAIL_RUN_INCLUDE_ALL | testrail.runIncludeAll  | no              | Include all test cases in test run creation.<br />Values: true/false                                                                                                                  |
 | CYPRESS_TESTRAIL_RUN_CLOSE       | testrail.closeRun       | no (Mode B)     | Automatically close test runs.<br />Values: true/false                                                                                                                                |
 
-#### Use on CLI
+#### 7.1 Use on CLI
 
 To provide variables on CLI just expose them before executing your actual command.
 
 ```bash 
 CYPRESS_TESTRAIL_PROJECT_ID=2 CYPRESS_TESTRAIL_MILESTONE_ID=15 ./node_modules/.bin/cypress run 
 ```
 
-#### Use in cypress.env.json
+#### 7.2 Use in cypress.env.json
 
 You can also provide the variables in a JSON structure like this inside your **cypress.env.json** file.
 
@@ -234,6 +255,75 @@ You can also provide the variables in a JSON structure like this inside your **c
 }
 ```
 
-### Copying / License
+### 8. Using multiple Cypress plugins
+
+Let's start with the most important thing: The problem with the Cypress event listeners.
+
+This integration uses events like "before:run" and more.
+Unfortunately Cypress does not have a list of subscribed event handlers, that means if multiple plugins are using the same event, then they will overwrite each other.
+
+Thanks to @bahmutov we have a solution for this problem (https://github.com/bahmutov/cypress-on-fix).
+
+Please install his package "cypress-on-fix" as described on his website.
+
+### 9. Cucumber Gherkin Support
+
+This integration works with both, plain Cypress tests but also in combination
+with the Cucumber plugin and Gherkin documents (https://github.com/badeball/cypress-cucumber-preprocessor).
+
+Once installed, you can easily prefix the titles of your **Scenario** entries with the TestRail case ID.
+Internally they are converted into Cypress tests, which means everything works as with the plain usage of tests.
+
+```markdown
+Feature: Blog Page Features
+
+Scenario: C123: Filter blog posts by tags
+Given I am on the blog page
+When I click on tag "testing"
+Then I see tag "testing" as title of the page
+```
+
+#### 9.1 Installation
+
+Please install the cucumber plugin for Cypress as described on their website.
+Also consider the problem of having multiple plugins using the same event listeners as described above.
+
+Once done, you need to configure Cucumber, our Cypress TestRail integration and the cypress-on-fix package.
+Here is a sample configuration with all 3 plugins being used (please note, this is just a sample):
+
+```javascript
+const createBundler = require('@bahmutov/cypress-esbuild-preprocessor');
+const {addCucumberPreprocessorPlugin} = require('@badeball/cypress-cucumber-preprocessor');
+const {createEsbuildPlugin} = require('@badeball/cypress-cucumber-preprocessor/esbuild');
+const {defineConfig} = require('cypress');
+const TestRailReporter = require('cypress-testrail');
+
+module.exports = defineConfig({
+    e2e: {
+        // sample to configure both, gerhkin documents and plain cypress tests
+        specPattern: ['cypress/e2e/**/*.feature', 'cypress/e2e/**/*.js'],
+
+        async setupNodeEvents(cypressOn, config) {
+            // prepare the fix for event listeners
+            const on = require('cypress-on-fix')(cypressOn)
+
+            // configure cucumber
+            await addCucumberPreprocessorPlugin(on, config);
+            on('file:preprocessor', createBundler({
+                plugins: [createEsbuildPlugin(config)],
+            }));
+
+            // configure TestRail
+            new TestRailReporter(on, config).register();
+
+            return config
+        },
+    },
+});
+```
+
+That's it! When you now run tests based on Gherkin documents, the TestRail integration will automatically send the results to TestRail.
+
+### 10. Copying / License
 
 This repository is distributed under the MIT License (MIT).