diff --git a/doc/events.md b/doc/events.md index 424b729af..22e582334 100644 --- a/doc/events.md +++ b/doc/events.md @@ -1,31 +1,294 @@ # Gemini events -* `CLI` - emitted right at start, before cli is parsed. Allows to add new commands and extend help message. The event is emitted with 1 argument `parser` which is the [commander](https://github.com/tj/commander.js) instance used inside gemini itself. +Events are listed in order they are emitted. -* `INIT` - emitted before any job start (`test`, `update` or `readTests`). If handler returns a promise then job will start only after the promise will be resolved. Emitted only once no matter how many times job will be performed. + + + + + -* `AFTER_TESTS_READ` - emitted after all tests were read (during `test`, `update` or `readTests` call). The event is emitted with 1 argument `data`: - * `data.suiteCollection` - suite collection with all suites parsed from test files + + + + -* `UPDATE_RESULT` — emitted always during update. The event is emitted with 1 argument `result`: - * `result.imagePath` — absolute path to the reference image - * `result.updated` — boolean value which is `true` when reference image have been changed and `false` when not + + + + -* `TEST_RESULT` — emitted always after the test is completed. The event is emitted with 1 argument `result`: - * `result.referencePath` — absolute path to the reference image - * `result.currentPath` — absolute path to the current image on your disk - * `result.equal` — boolean value which is `true` when images are equal and `false` when aren't - * `result.saveDiffTo` — function is responsible for building diff and present in the `result` only if images aren't equal + + + + -* `INTERRUPT` — emitted on signal events `SIGHUP`, `SIGINT` or `SIGTERM`. The event is emitted with 1 argument `data`: - * `data.exitCode` — exit code with which gemini will be interrupted + + + + -* `START_BROWSER` — emitted on browser session start. Emitted with [browser instance](../lib/browser/new-browser.js). If handler returns a promise tests will be executed in this session only after the promise is resolved. + + + + -* `STOP_BROWSER` — emitted right before browser session end. Emitted with [browser instance](../lib/browser/new-browser.js). If handler returns a promise quit will be performed only after the promise is resolved. + + + + -* `BEGIN` — runner event. Emitted on runner start with 1 argument `data`: - * `data.suiteCollection` — suite collection which will be run - * `data.config` — gemini config - * `data.totalStates` — number of states in collection - * `data.browserIds` — all browser ids from config + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EventDescription
CLI +Emitted right at start, before cli is parsed. Allows to add new commands and extend help message. +Event is emitted with 1 argument parser which is the +commander +instance used inside gemini itself. +
INIT +Emitted before any job start (test, update or readTests). +If handler returns a promise, then job will start only after the promise is resolved. +Emitted only once no matter how many times job is performed. +
BEFORE_FILE_READ +Emitted before each test file is read. Event is emitted with 1 argument filePath, +which is the absolute path to the file to be read. +
AFTER_FILE_READ +Emitted after each test file has been read. Event is emitted with 1 argument filePath +which is the absolute path to the file that was read. +
AFTER_TESTS_READ +Emitted after all tests were read (during test, update or readTests call). +Event is emitted with 1 argument data: +
+{
+    suiteCollection // suite collection with all suites parsed from test files
+}
+
+
START_RUNNER +Emitted before the start of test or update command. +If you return a promise from the event handler, the start of the command will be delayed until the promise resolves. +
BEGIN +Runner event. Emitted on runner start with 1 argument data: +
+{
+    suiteCollection, // suite collection which will be run
+    config,          // gemini config
+    totalStates,     // number of states in collection
+    browserIds       // all browser ids from config
+}
+
+
BEGIN_SUITE +Emitted before decide if should test suite in specified browser. Event is emitted with 1 argument data: +
+{
+    suite,
+    browserId
+}
+
+
SKIP_STATE +Emitted if browser is skipped in this state. Event is emitted with 1 argument data: +
+{
+    suite,
+    state,
+    browserId
+}
+
+
START_BROWSER +Emitted on browser session start. Emitted with +browser instance. +If handler returns a promise, tests will be executed in this session only after the promise is resolved. +
BEGIN_STATE +Emitted before launching browser for test. Event is emitted with 1 argument data: +
+{
+    suite,
+    state,
+    browserId,
+    sessionId
+}
+
+
UPDATE_RESULT +Emitted always during update. Event is emitted with 1 argument result: +
+{
+    imagePath, // absolute path to the reference image
+    updated,   // shows if reference image has been changed
+    suite,
+    state,
+    browserId,
+    sessionId
+}
+
+
RETRY +Emitted if test has failed but there is still number of retries left. +Event is emitted with 1 argument result: +
+{
+    referencePath, // absolute path to the reference image
+    currentPath,   // absolute path to the current image on your disk
+    equal,         // always false for retries
+    tolerance,     // specified for current test or globally in .gemini.js
+    saveDiffTo,    /* function responsible for building diff and present
+                      in the result only if images aren't equal */
+    attempt,       // number of retry for browser in current test
+    retriesLeft,   /* number of left retries > 0, when number hits 0
+                      event TEST_RESULT is called instead */
+    suite,
+    state,
+    browserId,
+    sessionId
+}
+
+
TEST_RESULT +Emitted always after the test is completed. Event is emitted with 1 argument result: +
+{
+    referencePath, // absolute path to the reference image
+    currentPath,   // absolute path to the current image on your disk
+    equal,         // shows if images are equal
+    tolerance,     // specified for current test or globally in .gemini.js
+    saveDiffTo,    /* function responsible for building diff and present
+                      in the result only if images aren't equal */
+    suite,
+    state,
+    browserId,
+    sessionId
+}
+
+
END_STATE +Emitted right after UPDATE_RESULT and TEST_RESULT with 1 argument data: +
+{
+    suite,
+    state,
+    browserId,
+    sessionId
+}
+
+
STOP_BROWSER +Emitted right before browser session end. Emitted with +browser instance. +If handler returns a promise, quit will be performed only after the promise is resolved. +
END_SUITE +Emitted right after suite is skipped or tested in specified browser. Emitted with 1 argument data: +
+{
+    suite,     // tested suite
+    browserId, // skipped or tested browser
+}
+
+
ERROR +Emitted with 1 argument err, which is an instance of Error +and has additional fields depending on the cause of error. + +For example, if Reference image is missing, err will have additional fields: + +
+{
+    currentPath,
+    refImagePath,
+    suite,
+    state,
+    browserId,
+    sessionId
+}
+
+
INTERRUPT +Emitted on signal events SIGHUP, SIGINT or SIGTERM. +The event is emitted with 1 argument data – {exitCode}, wich is +
    +
  • 129 for SIGHUP +
  • 130 for SIGINT +
  • 143 for SIGTERM +
+
END +Emitted when all tests are completed with 1 argument stat, which contains statistics for tests. + +For example: + +
+{
+    total: 6,
+    updated: 0,
+    passed: 2,
+    failed: 1,
+    skipped: 3,
+    retries: 8
+}
+
+
END_RUNNER +Emitted after the end of the test or update command. +
diff --git a/doc/programmatic-api.md b/doc/programmatic-api.md index 69f2c73dd..63e8e1a8b 100644 --- a/doc/programmatic-api.md +++ b/doc/programmatic-api.md @@ -220,20 +220,9 @@ gemini configuration. ## Events `gemini` instance emits some events, which can be used by external scripts or -plugins: +plugins. -* `START_RUNNER` — emitted before the start of `test` or `update` command. If - you return a promise from the event handler, the start of the command will - be delayed until the promise resolves. - -* `END_RUNNER` — emitted after the end of the `test` or `update` command. - -* `BEFORE_FILE_READ` — emitted before each test file is read. The event is emitted - with 1 argument `filePath` which is the absolute path to the file to be read. - -* `AFTER_FILE_READ` — emitted after each test file have been read. The event is - emitted with 1 argument `filePath` which is the absolute path to the file that - was read. +[See the details](../doc/events.md) about available events. Plugin example with the listening on the events: ```javascript