Merge pull request #264 from veghdev/integrationtest_doc

Integration test more detailed documentation

Author: veghdev

test/integration/man.js

@@ -3,6 +3,19 @@ const yargs = require("yargs");
 const Manual = require("./modules/manual/manual.js");
 
 try {
+  var usage = `
+Usage: $0 [tests] [options]
+
+This program allows for the manual testing of Vizzu. The program provides the following options:
+
+Select Vizzu version in the first column to use for playing animations on the left canvas.
+Select Vizzu version in the second column to use for playing animations on the right canvas.
+This enables comparison between the two versions and helps identify any differences.
+
+Select a test case in the third column to play.
+The animation of the selected test case will be displayed using the chosen Vizzu versions.
+`;
+
   var argv = yargs
     .usage("Usage: $0 [tests] [options]")
 
@@ -20,9 +33,8 @@ try {
     .nargs("c", 1)
     .describe(
       "c",
-      "Change the list of config file's path of the test cases" +
-        "\n(relative or absolute path where the repo folder is the root)" +
-        "\n"
+      "Change the list of configuration files' path of the test cases" +
+        "\n(relative or absolute path where the repo folder is the root)"
     )
     .default("c", [
       "/test/integration/test_cases/test_cases.json",

test/integration/test.js

@@ -18,17 +18,28 @@ const catchError = (err) => {
 };
 
 try {
+
+  var usage = `
+Usage: $0 [tests] [options]
+
+The integration test aims to comprehensively test the Vizzu library by executing animations represented as a promise chain of animate function calls.
+Each test case follows predefined animation steps and calculates a hash based on the generated canvas image data for each step.
+The test validation compares the calculated hash values with the expected values stored for each test case.
+
+The test offers the ability to generate and save images for every canvas image data, as well as create reference and difference images.
+This allows for detailed analysis and comparison of the test output.
+
+During testing, two types of warnings may occur.
+Firstly, if a test case lacks a stored reference hash, a warning is issued.
+Secondly, if a test case produces a different hash compared to the stored reference, but the reference Vizzu library also generates the same hash,
+it indicates that the difference is likely caused by environmental factors such as the operating system or the browser.
+
+Please note that the test require Chrome, ChromeDriver and Selenium Webdriver to be properly configured and available.
+`;
+
   var argv = yargs
 
-    .usage(
-      "Usage: $0 [tests] [options]" +
-        "\n\nThe objective of the integration test is to E2E test the Vizzu library." +
-        "\nThe test cases are animations, each animation consists of an animate function call promise chain." +
-        "\nThe test animations run in Chrome using ChromeDriver and Selenium Webdriver." +
-        "\nA test case seeks through each animate function calls with a predefined animation step." +
-        "\nA hash is calculated on every created canvas image data for each animation step." +
-        "\nA test validates a hash calculated from the created hash list during each test case."
-    )
+    .usage(usage)
 
     .help("h")
     .alias("h", "help")
@@ -43,9 +54,8 @@ try {
     .nargs("c", 1)
     .describe(
       "c",
-      "Change the list of config file's path of the test cases" +
-        "\n(relative or absolute path where the repo folder is the root)" +
-        "\n"
+      "Change the list of configuration files' path of the test cases" +
+        "\n(relative or absolute path where the repo folder is the root)"
     )
     .default("c", [
       "/test/integration/test_cases/test_cases.json",
@@ -55,7 +65,7 @@ try {
     .choices("Werror", ["noref", "sameref"])
     .describe(
       "Werror",
-      "Select warnings to be treated as errors" +
+      "Select warnings to be treated as errors during the test execution" +
         '\n- "noref": Test cases without reference hashes' +
         '\n- "sameref": Test cases that produce the same hashes with the reference Vizzu'
     )
@@ -69,7 +79,7 @@ try {
     .choices("images", ["ALL", "FAILED", "DISABLED"])
     .describe(
       "images",
-      "Change report images saving behavior" +
+      "Change the saving behavior of images, which are captured from every test steps" +
         '\n- "ALL": Create images for every test' +
         '\n- "FAILED": Create images for failed/warning tests only' +
         '\n- "DISABLED": Do not create images'
@@ -79,7 +89,7 @@ try {
     .choices("hashes", ["ALL", "FAILED", "DISABLED"])
     .describe(
       "hashes",
-      "Change report hashes saving behavior" +
+      "Change the saving behavior of hashes, which are unique identifiers calculated for each test case" +
         '\n- "ALL": Write hashes into the report file for every test' +
         '\n- "FAILED": Write hashes into the report file for failed/warning tests only' +
         '\n- "DISABLED": Do not create report file'
@@ -89,7 +99,7 @@ try {
     .boolean("nologs")
     .describe(
       "nologs",
-      "\n Do not save browser and console log into file" + "\n"
+      "Disable the saving of browser and console logs into a log file"
     )
     .default("nologs", false)
 
@@ -99,16 +109,15 @@ try {
       "vizzu",
       "Change Vizzu url" +
         "\n(can be forced to use vizzu.js or vizzu.min.js if its given)" +
-        '\n\n- "head": select the last stable Vizzu from the main branch' +
+        '\n\n- "head": specify "head" to select the last stable version of Vizzu from the main branch' +
         "\n(default: vizzu.min.js)" +
         "\n\n- [sha]: select Vizzu with a short commit number" +
         "\n(default: vizzu.min.js)" +
         "\n\n- [version]: select Vizzu with a version number" +
         "\n(vizzu.min.js only)" +
         "\n\n- path: select Vizzu from the local file system" +
         "\n(relative or absolute path where the repo folder is the root)" +
-        "\n(default: vizzu.js)" +
-        "\n"
+        "\n(default: vizzu.js)"
     )
     .default("vizzu", "/example/lib/vizzu.js")
 
@@ -118,32 +127,31 @@ try {
       "vizzu-ref",
       "Change reference Vizzu url" +
         "\n(can be forced to use vizzu.js or vizzu.min.js if its given)" +
-        '\n\n- "head": select the last stable Vizzu from the main branch' +
+        '\n\n- "head": specify "head" to select the last stable version of Vizzu from the main branch' +
         "\n(default: vizzu.min.js)" +
         "\n\n- [sha]: select Vizzu with a short commit number" +
         "\n(default: vizzu.min.js)" +
         "\n\n- [version]: select Vizzu with a version number" +
         "\n(vizzu.min.js only)" +
         "\n\n- path: select Vizzu from the local file system" +
         "\n(relative or absolute path where the repo folder is the root)" +
-        "\n(default: vizzu.js)" +
-        "\n"
+        "\n(default: vizzu.js)"
     )
     .default("vizzu-ref", "head")
 
     .boolean("g")
     .alias("g", "gui")
-    .describe("g", "Use browser with graphical user interface" + "\n")
+    .describe("g", "Use browser with graphical user interface")
     .default("g", false)
 
     .number("b")
     .alias("b", "browsers")
-    .describe("b", "Change number of parallel browser windows" + "\n")
+    .describe("b", "Change number of parallel browser windows")
     .default("b", 6)
 
     .boolean("d")
     .alias("d", "delete")
-    .describe("d", "Delete test report folder" + "\n")
+    .describe("d", "Delete test report folder")
     .default("d", false)
 
     .example([
@@ -166,17 +174,17 @@ try {
         "Select test cases with glob pattern",
       ],
     ])
-    .example(
-      "$0 -g",
-      "Run all tests and use browser with graphical user interface"
-    )
     .example([
       [
-        "$0 -vizzu head",
+        "$0 --vizzu head",
         "Run all tests with the latest stable Vizzu from the main branch",
       ],
       [
-        "$0 -vizzu [sha]/vizzu.js",
+        "$0 --vizzu [x.y.z]",
+        "Run all tests and select Vizzu with a version number",
+      ],
+      [
+        "$0 --vizzu [sha]/vizzu.js",
         "Run all tests and select Vizzu with a short commit number" +
           "\nand use vizzu.js instead of the default vizzu.min.js",
       ],

test/test.md

@@ -39,53 +39,77 @@ npm test -- -t <test name>
 
 # Integration testing
 
-## Install all test dependencies on Ubuntu 20.04
-
-Add Node.js to the repository list:
+For information on how integration testing works and what options it has, please see the program help:
 
 ```
-wget --quiet -O - https://deb.nodesource.com/setup_18.x | sudo bash
+cd test/integration
+node test.js --help
 ```
 
-Install test dependencies:
+## Test environment
+
+It is recommended to use `Ubuntu 22.04` and setup the test environment with the steps below.
+
+Install package dependencies:
 
 ```
 sudo apt-get update
-sudo apt-get install nodejs fonts-roboto fonts-noto-cjk gnupg wget curl unzip
+sudo apt-get install fonts-roboto fonts-noto-cjk gnupg wget curl unzip
 ```
 
-Install or update latest chrome and chromedriver:
+It is recommended to use `Node.js 18`.
+Install `nvm` and `Node.js 18`:
 
 ```
-npm run chrome
+wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
+export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
+[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
+
+nvm install 18
+nvm use default 18
+
+node --version
 ```
 
-## Testing the project
+Note: We use the latest `Chrome` and `Chromedriver` to keep our library up to date.
+Install (or update) the latest `Chrome` and `Chromedriver`:
+
+```
+npm run chrome
+```
 
-### Install NPM dependencies:
+Install `npm` package dependencies:
 
 ```
 cd test/integration
 npm install  # npm update
 ```
 
-### Run all tests
+## Run all test cases
 
 ```
 cd test/integration
 node test.js
-# For more information run: node test.js -h
 ```
 
-#### Manual testing
+For more options please see the program help.
+
+```
+node test.js --help
+```
 
-Test cases can be viewed using different versions of vizzu using the manual checker.\
-Note: select version of Vizzu on the left (where HEAD is the latest stable)\
-Note: select test case on the right
+## Manual testing
+
+Test cases can be viewed using different versions of vizzu using the manual checker.
 
 ```
 cd test/integration
 node man.js
 # Press CTRL and click on the URL to open it in the default browser
-# For more information run: node man.js -h
 ```
+
+For more options please see the program help.
+
+```
+node man.js --help
+```