WL#15353: add support for running tests in a container

In order to run the automated test suite, and besides a running MySQL
server instance, users need to have a previously installed compatible
Node.js engine version and, additionally, need to install the required
3rd-party dependencies.

Although very little, this process always requires a bit of Node.js
expertise, and can be a hurdle for developers that want to test specific
server features, and not the corresponding client/connector UX.

One way to introduce a small shortcut and reduce the burden of setting
up a local testing environment is by leveraging docker containers. In
this case, users would only need to install the container engine, and
any additional setup would be performed automatically and without
requiring any specific language/platform knowledge apart from knowing to
execute a shell script in the system and launching the MySQL server.

This patch introduces tooling that facilitates the task of running the
test suite using a docker container and a running MySQL server instance
on Unix-based environments (such as Linux and macOS). It delivers a
shell script that automates the task of building the container image and
run it using the exact same configuration parameters that can be
specified whilst in the local system environment.

At the same time, it removes some older tooling used to facilitate a
similar task which was not in any way tied to the existing public npm
scripts and was, at best, a source of confusion.

Change-Id: I2a5fdaf8edb15fd6be5f70d7457a293fe7d1d6e3

Author: ruiquelhas

CONTRIBUTING.md

@@ -60,10 +60,11 @@ $ npm run test:functional
 If the server is not running on the same machine, is available only via a local UNIX socket, or if it is initialized using other custom configuration details, those can be provided to the test runner using the following environment variables:
 
 * `MYSQLX_HOST` (`'localhost'` by default)
+* `MYSQLX_DEFAULT_SCHEMA` (`'nodejsmysqlxtest'` by default)
 * `MYSQLX_PASSWORD` (empty by default)
 * `MYSQLX_PORT` (`33060` by default)
 * `MYSQLX_SOCKET` (`undefined` by default)
-* `MYSQLX_DEFAULT_SCHEMA` (`'nodejsmysqlxtest'` by default)
+* `MYSQLX_USER` (`root` by default)
 
 For example:
 
@@ -80,6 +81,37 @@ $ npm run test
 $ npm run test:unit && npm run test:functional
 ```
 
+#### Using a Docker container
+
+Alternatively, for Linux or macOS users, there is a script that builds and runs a Docker container which then executes the test suite. This means no external dependency, apart from a running MySQL server, is needed.
+
+The script uses the environment variables described previously and introduces a few new ones. These are mostly meant to be used for configuring the Docker container itself. They allow to specify the path to a Node.js engine image, the network proxy setup and the URL of the NPM registry to use.
+
+* `BASE_IMAGE` (`container-registry.oracle.com/graalvm/nodejs:latest` by default)
+* `HTTP_PROXY` (value of the environment variable in the host by default)
+* `HTTPS_PROXY` (value of the environment variable in the host by default)
+* `NO_PROXY` (value of the environment variable in the host by default)
+* `NPM_REGISTRY` (`https://registry.npmjs.org/` by default)
+
+There is one additional environment variable called `TEST_PATTERN` which can be used to provide a string or a regular expression that is applied for filtering one or more matching tests to execute.
+
+Ultimately, the script allows an argument which identifies the underlying NPM script that gets executed. So, in theory, any of the available NPM scripts can be executed in the container, but by default, it will execute the `test` script.
+
+```sh
+ # executing the default test script with the default environment (Linux only)
+$ ./test/docker/run.sh
+# executing the unit test suite
+$ ./test/docker/run.sh test:unit
+# executing all TCP-based functional tests whose description matches the given pattern
+$ MYSQLX_HOST='<hostname_or_IP_address>' TEST_PATTERN='using CRUD' ./test/docker/run.sh test:functional
+# executing all functional tests (Linux only)
+$ MYSQLX_SOCKET='/path/to/socket' ./test/docker/run.sh test:functional
+```
+
+Similar to when the tests run on a local environment, the `MYSQLX_HOST` variable is only relevant for the functional tests. On Linux, the variable is optional and the Docker container will run using the "host" network mode whilst tests assume the MySQL server is listening on `localhost`. On macOS, since containers run on a virtual machine, host loopback addresses are not reachable. In that case, the `MYSQLX_HOST` variable is required and should specify the hostname or IP address of the MySQL server.
+
+Due to some [know limitations](https://github.com/docker/for-mac/issues/483) on the macOS Docker architecture, Unix socket tests can only run on Linux. In that case, if the `MYSQLX_SOCKET` variable is explicitely specified, a shared volume between the host and the container will be created as a mount point from the socket file path in the host and an internal container directory specified as a volume, where the socket file path becomes available.
+
 ### Test Coverage
 
 When submitting a patch that introduces changes to the source code, you need to make sure that those changes are be accompanied by a proper set of tests that cover 100% of the affected code paths. This is easily auditable by generating proper test coverage HTML and stdout reports using the following command:

bin/wait-for.js

@@ -56,9 +56,8 @@
     "lint": "npm run lint:lib && npm run lint:types",
     "mocha": "mocha --reporter spec --timeout 10000 --recursive",
     "prepack": "node bin/prepack.js",
-    "pretest": "node bin/wait-for.js",
     "test": "tsd && npm run mocha test/unit test/functional/default",
-    "test:functional": "npm run pretest && npm run mocha test/functional/default",
+    "test:functional": "npm run mocha test/functional/default",
     "test:unit": "npm run mocha test/unit",
     "test:types": "tsd"
   },

package.json

@@ -0,0 +1,64 @@
+# Copyright (c) 2022, Oracle and/or its affiliates.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License, version 2.0, as
+# published by the Free Software Foundation.
+#
+# This program is also distributed with certain software (including
+# but not limited to OpenSSL) that is licensed under separate terms,
+# as designated in a particular file or component or in included license
+# documentation.  The authors of MySQL hereby grant you an
+# additional permission to link the program and your derivative works
+# with the separately licensed software that they have included with
+# MySQL.
+#
+# Without limiting anything contained in the foregoing, this file,
+# which is part of MySQL Connector/Node.js, is also subject to the
+# Universal FOSS Exception, version 1.0, a copy of which can be found at
+# http://oss.oracle.com/licenses/universal-foss-exception.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See the GNU General Public License, version 2.0, for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA
+
+# By default, the container will use the latest GraalVM Node.js image
+# from OCR. The BASE_IMAGE environment variable can be used to pull
+# any other Node.js image from any other Docker registry.
+ARG BASE_IMAGE=container-registry.oracle.com/graalvm/nodejs:latest
+FROM ${BASE_IMAGE}
+
+# In order to be able to run the tests within a private network, optional
+# proxy configurations can be used.
+ARG HTTP_PROXY
+ARG HTTPS_PROXY
+ARG NO_PROXY
+ENV HTTP_PROXY=${HTTP_PROXY} HTTPS_PROXY=${HTTPS_PROXY} NO_PROXY=${NO_PROXY}
+
+WORKDIR /mysql-connector-nodejs
+
+# The package.json file needs to exist before the 3rd-party dependencies
+# are installed.
+COPY package.json .
+
+# It is possible to use a private NPM registry.
+ARG NPM_REGISTRY=https://registry.npmjs.org/
+RUN npm config set registry ${NPM_REGISTRY}
+RUN npm install --quiet
+
+# This volume can be used to share, among other things, the Unix socket file
+# with the container.
+VOLUME [ "/shared" ]
+
+# Artifacts are copied according to how much they might change in the future
+# to leverage layer caching.
+COPY .eslintrc.js .
+COPY bin bin
+COPY index.js .
+COPY types types
+COPY test test
+COPY lib lib

test/docker/Dockerfile

@@ -0,0 +1,90 @@
+# Copyright (c) 2022, Oracle and/or its affiliates.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License, version 2.0, as
+# published by the Free Software Foundation.
+#
+# This program is also distributed with certain software (including
+# but not limited to OpenSSL) that is licensed under separate terms,
+# as designated in a particular file or component or in included license
+# documentation.  The authors of MySQL hereby grant you an
+# additional permission to link the program and your derivative works
+# with the separately licensed software that they have included with
+# MySQL.
+#
+# Without limiting anything contained in the foregoing, this file,
+# which is part of MySQL Connector/Node.js, is also subject to the
+# Universal FOSS Exception, version 1.0, a copy of which can be found at
+# http://oss.oracle.com/licenses/universal-foss-exception.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See the GNU General Public License, version 2.0, for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA
+
+#!/bin/sh
+
+image=mysql-connector-nodejs
+version=${MYSQL_VERSION:-latest}
+input_test_script=$1
+test_script=${input_test_script:-test}
+basedir=$(dirname $0)
+
+# The BASE_IMAGE, HTTPS_PROXY, HTTP_PROXY, NO_PROXY and NPM_REGISTRY
+# environment variables are used as build arguments. Unless they are
+# explicitly specified, the script will use their system-wide values.
+# It should be possible to run script from anywhere in the file system. So,
+# the absolute Dockerfile and context paths should be specified.
+docker build \
+    --build-arg BASE_IMAGE \
+    --build-arg HTTP_PROXY \
+    --build-arg HTTPS_PROXY \
+    --build-arg NO_PROXY \
+    --build-arg NPM_REGISTRY \
+    --tag $image:$version \
+    --file $basedir/Dockerfile \
+    $basedir/../../
+
+# If MYSQLX_HOST is empty, "localhost" should be used by default.
+# The variable needs to be re-assigned in order to determine if it contains a
+# loopback address (implicitly or explicitly).
+if [ -z "$MYSQLX_HOST" ]
+then
+    MYSQLX_HOST="localhost"
+fi
+
+# If MYSQLX_HOST is a loopback address, a new flag is created. This flag
+# allows to determine the network mode in which the Docker container will
+# run. The container should run in "host" mode if MYSQLX_HOST is a loopback
+# address and should run in "bridge" mode (default) if MYSQLX_HOST is
+# a different host name or IP address.
+if [ "$MYSQLX_HOST" == "localhost" ] || [ "$MYSQLX_HOST" == "127.0.0.1" ]
+then
+    MYSQL_LOCALHOST=$MYSQLX_HOST
+fi
+
+# If MYSQLX_SOCKET is not empty, the corresponding path to the Unix socket
+# file should be shared with the container using a Docker volume.
+# Additionally, the variable should be assigned the appropriate absolute
+# file path from the container standpoint.
+# If MYSQL_LOCALHOST is not empty, the container should run using the "host"
+# network mode. If it is empty, the container should run using the "bridge"
+# network mode, which is what happens by default.
+docker run \
+    --rm \
+    --interactive \
+    --tty \
+    ${MYSQL_LOCALHOST:+ --network host} \
+    ${MYSQLX_SOCKET:+ --volume $MYSQLX_SOCKET:/shared/mysqlx.sock} \
+    --env MYSQLX_HOST \
+    --env MYSQLX_PASSWORD \
+    --env MYSQLX_PORT \
+    ${MYSQLX_SOCKET:+ --env MYSQLX_SOCKET=/shared/mysqlx.sock} \
+    --env MYSQLX_USER \
+    --env TEST_PATTERN \
+    $image:$version \
+    npm run $test_script -- -- --grep "$TEST_PATTERN"