test(e2e): adds e2e tests using snapshot images

Implements integration tests with Jest for testing snapshots of PS and
SVG images, and image snapshots of PNG ones. Updates documentation with
relevant examples from e2e tests.

Author: jshor

.gitignore

@@ -7,3 +7,5 @@ build
 .zint
 lib
 .nyc_output
+test/e2e/__rendered__/*
+!test/e2e/__rendered__/.keep

.npmignore

@@ -0,0 +1,6 @@
+test
+docs
+build
+lib
+.zint
+.github

commitlint.config.js

@@ -1 +1,3 @@
-module.exports = {extends: ['@commitlint/config-conventional']}
+module.exports = {
+  extends: ['@commitlint/config-conventional']
+}

docs/guide/symbologies/one-dimensional.md

@@ -8,6 +8,16 @@ One-Dimensional symbols are what most people associate with the term barcode. Th
 
 Developed by Intermec in 1977, Code 11 is similar to [Code 2 of 5 Matrix](#code-2-of-5) and is primarily used in telecommunications. The symbol can encode any length string consisting of the digits `0-9` and the dash character (`-`). One modulo-11 check digit is calculated.
 
+#### Example
+
+The following will render a Code 11 symbol encoding `8765432164`:
+
+```js
+symbology.createStream({
+  symbology: symbology.Barcode.CODE11
+}, '8765432164')
+```
+
 ## Code 2 of 5
 
 ![ITF-14](/assets/barcodes/barcode_15.png)
@@ -18,6 +28,17 @@ Code 2 of 5 is a family of one-dimensional symbols, 8 of which are supported. No
 
 Also known as **Code 2 of 5 Matrix**, this symbology is a self-checking code used in industrial applications and photo development. Standard Code 2 of 5 will encode any length numeric input (digits `0-9`).
 
+#### Example
+
+The following will render a standard Code 2 of 5 symbol encoding `32109876543211`:
+
+```js
+symbology.createStream({
+  symbology: symbology.Barcode.C25IATA,
+  borderWidth: 6
+}, '32109876543211')
+```
+
 ### IATA Code 2 of 5
 
 Used for baggage handling in the air-transport industry by the International Air Transport Agency, this self-checking code will encode any length numeric input (digits `0-9`) and does not include a check digit.
@@ -58,9 +79,9 @@ UPC-A is used in the United States for retail applications. The symbol requires
 
 ```js
 symbology.createStream({
-  symbology: Symbology.Barcode.UPCA,
-  mode: 1, // TODO
-  primary: '331234567890', // TODO
+  symbology: symbology.Barcode.UPCA,
+  mode: 1,
+  primary: '331234567890'
 }, '72527270270+12345')
 ```
 
@@ -80,7 +101,7 @@ This library also supports Number System 1 encoding by entering a 7-digit articl
 
 ```js
 symbology.createStream({
-  symbology: Symbology.Barcode.UPCE
+  symbology: symbology.Barcode.UPCE
 }, '1123456')
 ```
 
@@ -110,7 +131,7 @@ The following example will encode a standalone EAN-5:
 
 ```js
 symbology.createStream({
-  symbology: Symbology.Barcode.EANX
+  symbology: symbology.Barcode.EANX
 }, '54321')
 ```
 
@@ -162,11 +183,24 @@ The table below shows the options available:
 | 3                  | Modulo-11             |
 | 4                  | Modulo-11 & Modulo-10 |
 
+
+#### Example
+
+The following example will create an MSI Plessey symbol with modulo-10 check digit encoding `7432365`:
+
+```js
+symbology.createStream({
+  symbology: symbology.Barcode.MSI_PLESSEY,
+  option2: 1
+}, '7432365')
+```
+
 :::tip Note
 Any length numeric (digits `0-9`) input can be encoded.
 :::
 
 ## Telepen
+
 ### Telepen Alpha
 
 ![Telepen](/assets/barcodes/barcode_19.png)
@@ -187,6 +221,16 @@ Data can consist of pairs of numbers or pairs consisting of a numerical digit fo
 
 Standard Code 39 was developed in 1974 by Intermec. Input data can be of any length and can include the characters `0-9`, `A-Z`, dash (`-`), full stop (`.`), space (` `), asterisk (`*`), dollar (`$`), slash (`/`), plus (`+`) and percent (`%`).
 
+#### Example
+
+The following example will create a Code 39 symbol with modulo-10 check digit encoding `CODE39`:
+
+```js
+symbology.createStream({
+  symbology: symbology.Barcode.CODE39
+}, 'CODE39')
+```
+
 :::tip Note
 The standard does not require a check digit, but a modulo-43 check digit can be added via `option2`.
 :::
@@ -249,6 +293,16 @@ No check digit is generated.
 
 Developed by Laetus, Pharmacode is used for the identification of pharmaceuticals. The symbology is able to encode whole numbers between `3` and `131070`.
 
+#### Example
+
+The following example will create a Pharmacode symbol with modulo-10 check digit encoding `131070`:
+
+```js
+symbology.createStream({
+  symbology: symbology.Barcode.PHARMA
+}, '131070')
+```
+
 ## Code 128
 
 ### Standard Code 128 (ISO 15417)
@@ -377,6 +431,17 @@ The maximum values permitted depend on the number of channels used:
 | 7        | 000000        | 576688        |
 | 8        | 0000000       | 7742862       |
 
+#### Example
+
+The following example renders a 5-channel Channel Code symbol:
+
+```js
+symbology.createStream({
+  symbology: symbology.Barcode.CHANNEL,
+  option2: 6
+}, '12345')
+```
+
 :::tip Note
 Channel codes `7` and `8` require a processor-intensive algorithm to generate and so response times when generating these codes will be relatively slow.
-:::
+:::

docs/guide/symbologies/stacked.md

@@ -10,6 +10,17 @@ This is a stacked symbology based on [Code 128](one-dimensional.md#code-128) whi
 
 The width of the Codablock-F symbol can be specified via `option2` **or** the height (number of rows) can be specified via `option1`. The encoding of GS1 data in Codablock-F symbols is not supported.
 
+#### Example
+
+The following renders a a 5-row Codablock-F symbol:
+
+```js
+symbology.createStream({
+  symbology: symbology.Barcode.CODABLOCKF,
+  option1: 5,
+}, '11010000100101111011101001000011010100011000101000110001010001100010100011000110011001101100011101011')
+```
+
 ## Code 16k (EN 12323)
 
 ![Code 16K](/assets/barcodes/barcode_27.png)
@@ -40,6 +51,17 @@ The width of the generated PDF417 symbol can be specified by setting `option2` t
 A separate symbology ID can be used to encode [Health Industry Barcode (HIBC)](one-dimensional.md#hibc-code-39) data which adds a leading `+` character and a modulo-49 check digit to the encoded data.
 :::
 
+#### Example
+
+The following renders a 5-row Codablock-F symbol:
+
+```js
+symbology.createStream({
+  symbology: symbology.Barcode.CODABLOCKF,
+  option1: 5,
+}, '11010000100101111011101001000011010100011000101000110001010001100010100011000110011001101100011101011')
+```
+
 ## Compact PDF417
 
 Also known as truncated PDF417. Options are the same as for PDF417 above.
@@ -104,8 +126,18 @@ The width of the symbol can be altered by setting `option2` to the desired width
 This symbol can be generated with a two-dimensional component to make a composite symbol. For symbols with a 2D component, the number of columns must be at least `2`.
 :::
 
+#### Example
+
+```js
+symbology.createStream({
+  symbology: symbology.Barcode.EANX_CC,
+  option1: 1,
+  primary: '331234567890'
+}, '[99]1234-abcd')
+```
+
 ## Code 49
 
 ![Code 49](/assets/barcodes/barcode_33.png)
 
-Developed in 1987 at Intermec, Code 49 is a cross between UPC and Code 39. It it one of the earliest stacked symbologies and influenced the design of Code 16K a few years later. It supports full 7-bit ASCII input up to a maximum of 49 characters or 81 numeric digits. GS1 data encoding is also supported.
+Developed in 1987 at Intermec, Code 49 is a cross between UPC and Code 39. It it one of the earliest stacked symbologies and influenced the design of Code 16K a few years later. It supports full 7-bit ASCII input up to a maximum of 49 characters or 81 numeric digits. GS1 data encoding is also supported.

docs/guide/symbologies/two-dimensional.md

@@ -88,6 +88,17 @@ Four levels of error correction are available by setting `option1` to one of the
 | 3     | Q           | Approx 55% of symbol      | Approx 25%        |
 | 4     | H           | Approx 65% of symbol      | Approx 30%        |
 
+#### Example
+
+The following example creates a QR code:
+
+```js
+symbology.createStream({
+  symbology: symbology.Barcode.QRCODE,
+  option2: 1
+}, '12345')
+```
+
 ### QR Code Size
 
 The size of the symbol can be set to the QR Code version required (1-40). The size of symbol generated can be set by passing `option2` to one of the following input values:
@@ -170,11 +181,11 @@ The following example creates a symbol from data saved in an ISO-8859-2 file:
 
 ```js
 symbology.createStream({
-  symbology: Symbology.Barcode.MAXICODE,
+  symbology: symbology.Barcode.UPNQR,
   option1: 2,
   borderWidth: 5,
   scale: 3,
-  inputMode: symbology.InputModes.DATA_MODE
+  inputMode: symbology.Encoding.DATA_MODE
 }, 'to je testna črtna koda')
 ```
 
@@ -206,7 +217,7 @@ The primary message can be set via the `primary` option. The secondary message u
 
 ```js
 symbology.createStream({
-  symbology: Symbology.Barcode.MAXICODE,
+  symbology: symbology.Barcode.MAXICODE,
   option1: 2,
   primary: '999999999840012'
 }, 'Secondary Message Here')
@@ -228,7 +239,7 @@ Modes `4`, `5`, and `6` do not require a primary message.
 
 ```js
 symbology.createStream({
-  symbology: Symbology.Barcode.MAXICODE,
+  symbology: symbology.Barcode.MAXICODE,
   option1: 4
 }, 'A MaxiCode Message in Mode 4')
 ```
@@ -312,6 +323,18 @@ To specify the desired size of the symbol, set `option2` to one of the following
 | 17    | 71 x 71     | 35    | 147 x 147   |
 | 18    | 75 x 75     | 36    | 151 x 151   |
 
+#### Example
+
+The following will render a 45x45 Aztec Code symbol with 23% error correction capacity:
+
+```js
+symbology.createStream({
+  symbology: symbology.Barcode.AZTEC,
+  option1: 2,
+  option2: 11
+}, '12345')
+```
+
 :::tip Note
 The symbols marked with an asterisk (*) in the table below are "compact" symbols, meaning they have a smaller bulls-eye pattern at the centre of the symbol.
 :::
@@ -326,6 +349,16 @@ It is not possible to select both symbol size and error correction capacity for
 
 Defined in [ISO/IEC 24778 (Annex A)](https://www.iso.org/standard/41548.html), a truncated version of compact [Aztec Code](l#aztec-code-iso-24778) for encoding whole integers between `0` and `255`. Includes [Reed-Solomon error correction](https://en.wikipedia.org/wiki/Reed%E2%80%93Solomon_error_correction).
 
+#### Example
+
+The following will render an Aztec Runes symbol encoding `123`:
+
+```js
+symbology.createStream({
+  symbology: symbology.Barcode.AZRUNE
+}, '123')
+```
+
 ## Code One
 
 ![Code One](/assets/barcodes/barcode_50.png)
@@ -352,6 +385,17 @@ The type can be specified by setting `option2` to one of the following input val
 | 9     | S       | 8X height  | 18                    | **N/A**                    |
 | 10    | T       | 16X height | 90                    | 55                         |
 
+#### Example
+
+The following will render a 22x22 Code One symbol encoding `An Example`:
+
+```js
+symbology.createStream({
+  symbology: symbology.Barcode.CODEONE,
+  option2: 2
+}, 'An Example')
+```
+
 :::warning Important
 * Version `S` symbols can only encode numeric data.
 * The widths of version `S` and version `T` symbols are determined by the lengths of their input data.
@@ -405,6 +449,18 @@ The symbol size can be specified by setting the `option2` value to one of the fo
 | 12    | 150 x 150 |
 | 13    | 162 x 162 |
 
+#### Example
+
+The following will render a 30x30 Grid Matrix symbol with 20% error correction encoding `12345`:
+
+```js
+symbology.createStream({
+  symbology: symbology.Barcode.GRIDMATRIX,
+  option1: 2,
+  option2: 2
+}, '12345')
+```
+
 :::warning Important
 If you specify both of these values, this library will make a 'best-fit' attempt to satisfy both conditions.
 :::
@@ -419,6 +475,16 @@ DotCode uses a grid of dots in a rectangular formation to encode characters up t
 
 By default, the library will produce a symbol which is approximately square. However, the width of the symbol can be adjusted by setting `option2` to the desired width (in pixels).
 
+#### Example
+
+The following will render a DotCode symbol encoding `12345`:
+
+```js
+symbology.createStream({
+  symbology: symbology.Barcode.DOTCODE
+}, '12345')
+```
+
 :::warning Important
 Outputting DotCode to PNG will require setting the scale of the image to a larger value than the default (~10 pixels) for the dots to be plotted correctly.
 :::
@@ -507,6 +573,18 @@ The size of the symbol can be specified by setting `option2` to one of the follo
 | 41    | 103 x 103   | 83    | 187 x 187   |
 | 42    | 105 x 105   | 84    | 189 x 189   |
 
+#### Example
+
+The following will render a 33x33 Han Xin symbol encoding `12345` with ~23% error correction:
+
+```js
+symbology.createStream({
+  symbology: symbology.Barcode.HANXIN,
+  option1: 3,
+  option2: 6
+}, '12345')
+```
+
 :::warning Important
 It is not possible to select both symbol size and error correction capacity for the same symbol. If both options are selected then the error correction capacity selection will be ignored. 
 :::