From 84cc5406ef29b8a5fb5b892f4c8c04a940397535 Mon Sep 17 00:00:00 2001 From: Antonio Barcelos Date: Wed, 24 May 2023 12:56:13 +0200 Subject: [PATCH] Move build and test instructions to `CONTRIBUTING.md` and `TESTING.md` These information were spread into multiple `README.md` and present in the **npm package** description. However, this information is only useful for people who are contributing to the project. --- CONTRIBUTING.md | 22 ++++++ README.md | 87 --------------------- TESTING.md | 108 +++++++++++++++++++++++++++ packages/neo4j-driver-deno/README.md | 34 --------- packages/neo4j-driver-lite/README.md | 65 ---------------- packages/neo4j-driver/README.md | 87 --------------------- 6 files changed, 130 insertions(+), 273 deletions(-) create mode 100644 TESTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0cd82218c..64485aa08 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -48,6 +48,28 @@ We can't guarantee that we'll accept pull requests and may ask you to make some Occasionally, we might also have logistical, commercial, or legal reasons why we can't accept your work but we'll try to find an alternative way for you to contribute in that case. Remember that many community members have become regular contributors and some are now even Neo employees! +## Specifically for this project: + +All code in `packages/neo4j-driver-deno/lib` folder. Don't change it, this files should be update by running `npm run build::deno`. + +Setting up the development environment: + +* Install Node 12+ +* Install Deno 1.19+ +* Install Dependencies and Building +```bash +$ npm run ci +$ npm run build +``` + +After commit your changes, update the `neo4j-driver-deno` and commit the changes to the project: + +```bash +$ npm run build::deno +``` + +The build/testing pipelines will fail if the `neo4j-driver-deno` is not in sync with `neo4j-driver-lite`, `neo4j-driver-core` and `neo4j-driver-bolt-connection` source. + ## Got an idea for a new project? If you have an idea for a new tool or library, start by talking to other people in the community. diff --git a/README.md b/README.md index 587a55e44..a81d231a4 100644 --- a/README.md +++ b/README.md @@ -503,90 +503,3 @@ var driver = neo4j.driver( { disableLosslessIntegers: true } ) ``` - -## Building - -``` -npm ci -npm run build -``` - -This produces browser-compatible standalone files under `lib/browser` and a Node.js module version under `lib/`. -See files under `examples/` on how to use. - -## Testing - -Tests **require** latest [Testkit 4.3](https://github.com/neo4j-drivers/testkit/tree/4.3), Python3 and Docker. - -Testkit is needed to be cloned and configured to run against the Javascript Lite Driver. Use the following steps to configure Testkit. - -1. Clone the Testkit repository - -``` -git clone https://github.com/neo4j-drivers/testkit.git -``` - -2. Under the Testkit folder, install the requirements. - -``` -pip3 install -r requirements.txt -``` - -3. Define some enviroment variables to configure Testkit - -``` -export TEST_DRIVER_NAME=javascript -export TEST_DRIVER_REPO= -unset TEST_DRIVER_LITE -``` - -To run test against against some Neo4j version: - -``` -python3 main.py -``` - -More details about how to use Teskit could be found on [its repository](https://github.com/neo4j-drivers/testkit/tree/4.3) - -## Testing (Legacy) - -Tests **require** latest [Boltkit](https://github.com/neo4j-contrib/boltkit) and [Firefox](https://www.mozilla.org/firefox/) to be installed in the system. - -Boltkit is needed to start, stop and configure local test database. Boltkit can be installed with the following command: - -``` -pip3 install --upgrade boltkit -``` - -To run tests against "default" Neo4j version: - -``` -./runTests.sh -``` - -To run tests against specified Neo4j version: - -``` -./runTests.sh '-e 4.2.0' -``` - -Simple `npm test` can also be used if you already have a running version of a compatible Neo4j server. - -For development, you can have the build tool rerun the tests each time you change -the source code: - -``` -gulp watch-n-test -``` - -If the `gulp` command line tool is not available, you might need to install this globally: - -``` -npm install -g gulp-cli -``` - -### Testing on windows - -To run the same test suite, run `.\runTest.ps1` instead in powershell with admin right. -The admin right is required to start/stop Neo4j properly as a system service. -While there is no need to grab admin right if you are running tests against an existing Neo4j server using `npm test`. diff --git a/TESTING.md b/TESTING.md new file mode 100644 index 000000000..5be93b654 --- /dev/null +++ b/TESTING.md @@ -0,0 +1,108 @@ +# Neo4j Driver Testing + +## Unit Tests + +Unit tests **require** to setup the development environment as described at `CONTRIBUTING.md`. + +* To run unit tests for the whole project: + +```bash +$ npm run test::unit +``` + +* To run unit tests against only an specify module: + +```bash +$ npm run test::unit -- --scope="name-of-the-package" +``` + +* To run unit tests for each time a file is changed in a package: + +```bash +$ cd ./packages/name-of-package-folder +$ npm run test::watch +``` +Watch is not supported in the package `neo4j-driver`. + +**Warning!** When the change spread across multiple package, it might be need to rebuild the project to the changes be propagated before testing. + + +## Testing using Testkit + +Tests **require** latest [Testkit 5](https://github.com/neo4j-drivers/testkit/tree/5.0), Python3 and Docker. + +Testkit is needed to be cloned and configured to run against the Javascript Lite Driver. Use the following steps to configure Testkit. + +1. Clone the Testkit repository + +```bash +$ git clone https://github.com/neo4j-drivers/testkit.git +``` + +2. Under the Testkit folder, install the requirements. + +```bash +$ pip3 install -r requirements.txt +``` + +3. Define some environment variables to configure Testkit + +```bash +$ export TEST_DRIVER_NAME=javascript +$ export TEST_DRIVER_REPO= +``` + +By default, Testkit will run against the full version of the driver. +For testing the `neo4j-driver-lite`, the environment variable `TEST_DRIVER_LITE` should be set to `1`. +For testing the `neo4j-driver-deno`, the environment variable `TEST_DRIVER_DENO` should be set to `1`. + +To run test against against some Neo4j version: + +``` +python3 main.py +``` + +More details about how to use Testkit could be found on [its repository](https://github.com/neo4j-drivers/testkit/tree/5.0) + +## Testing (Legacy) + +Tests **require** latest [Boltkit](https://github.com/neo4j-contrib/boltkit) and [Firefox](https://www.mozilla.org/firefox/) to be installed in the system. + +Boltkit is needed to start, stop and configure local test database. Boltkit can be installed with the following command: + +``` +pip3 install --upgrade boltkit +``` + +To run tests against "default" Neo4j version: + +``` +./runTests.sh +``` + +To run tests against specified Neo4j version: + +``` +./runTests.sh '-e 4.2.0' +``` + +Simple `npm test` can also be used if you already have a running version of a compatible Neo4j server. + +For development, you can have the build tool rerun the tests each time you change +the source code: + +``` +gulp watch-n-test +``` + +If the `gulp` command line tool is not available, you might need to install this globally: + +``` +npm install -g gulp-cli +``` + +### Testing on windows + +To run the same test suite, run `.\runTest.ps1` instead in powershell with admin right. +The admin right is required to start/stop Neo4j properly as a system service. +While there is no need to grab admin right if you are running tests against an existing Neo4j server using `npm test`. diff --git a/packages/neo4j-driver-deno/README.md b/packages/neo4j-driver-deno/README.md index 26eaa3cec..537c5c3d7 100644 --- a/packages/neo4j-driver-deno/README.md +++ b/packages/neo4j-driver-deno/README.md @@ -58,37 +58,3 @@ quickly spin one up. For using system certificates, the `DENO_TLS_CA_STORE` should be set to `"system"`. `TRUST_ALL_CERTIFICATES` should be handle by `--unsafely-ignore-certificate-errors` and not by driver configuration. See, https://deno.com/blog/v1.13#disable-tls-verification; -## Tests - -Tests **require** latest [Testkit 5.0](https://github.com/neo4j-drivers/testkit/tree/5.0), Python3 and Docker. - -Testkit is needed to be cloned and configured to run against the Javascript Lite Driver. Use the following steps to configure Testkit. - -1. Clone the Testkit repository - -``` -git clone https://github.com/neo4j-drivers/testkit.git -``` - -2. Under the Testkit folder, install the requirements. - -``` -pip3 install -r requirements.txt -``` - -3. Define some enviroment variables to configure Testkit - -``` -export TEST_DRIVER_NAME=javascript -export TEST_DRIVER_REPO= -export TEST_DRIVER_DENO=1 -``` - -To run test against against some Neo4j version: - -``` -python3 main.py -``` - -More details about how to use Teskit could be found on [its repository](https://github.com/neo4j-drivers/testkit/tree/5.0) - diff --git a/packages/neo4j-driver-lite/README.md b/packages/neo4j-driver-lite/README.md index 39d851e9b..0c5c069cf 100644 --- a/packages/neo4j-driver-lite/README.md +++ b/packages/neo4j-driver-lite/README.md @@ -390,68 +390,3 @@ var driver = neo4j.driver( { disableLosslessIntegers: true } ) ``` - -## Building - -The build of this package is handled by the root package of this repository. - -First it is needed to install the mono-repo dependencies by running `npm ci` in the root of the repository. Then: - -* Build all could be performed with - -``` -npm run build -``` -* Build only the Core could be performed with -Builind only Core: -``` -npm run build -- --scope=neo4j-driver-lite - -``` - -This produces browser-compatible standalone files under `lib/browser` and a Node.js module version under `lib/`. -See files under `../examples/` on how to use. - -## Testing - -Tests **require** latest [Testkit 4.3](https://github.com/neo4j-drivers/testkit/tree/4.3), Python3 and Docker. - -Testkit is needed to be cloned and configured to run against the Javascript Lite Driver. Use the following steps to configure Testkit. - -1. Clone the Testkit repository - -``` -git clone https://github.com/neo4j-drivers/testkit.git -``` - -2. Under the Testkit folder, install the requirements. - -``` -pip3 install -r requirements.txt -``` - -3. Define some enviroment variables to configure Testkit - -``` -export TEST_DRIVER_NAME=javascript -export TEST_DRIVER_REPO= -export TEST_DRIVER_LITE=1 -``` - -To run test against against some Neo4j version: - -``` -python3 main.py -``` - -More details about how to use Teskit could be found on [its repository](https://github.com/neo4j-drivers/testkit/tree/4.3) - -Runing `npm test` in this package directory can also be used if you want to run only the unit tests. - -For development, you can have the build tool rerun the tests each time you change the source code: - -``` -npm run test:watch -``` - -The command `npm run test::unit` could be used in the root package for running the unit tests for all the packages in this project. diff --git a/packages/neo4j-driver/README.md b/packages/neo4j-driver/README.md index 587a55e44..a81d231a4 100644 --- a/packages/neo4j-driver/README.md +++ b/packages/neo4j-driver/README.md @@ -503,90 +503,3 @@ var driver = neo4j.driver( { disableLosslessIntegers: true } ) ``` - -## Building - -``` -npm ci -npm run build -``` - -This produces browser-compatible standalone files under `lib/browser` and a Node.js module version under `lib/`. -See files under `examples/` on how to use. - -## Testing - -Tests **require** latest [Testkit 4.3](https://github.com/neo4j-drivers/testkit/tree/4.3), Python3 and Docker. - -Testkit is needed to be cloned and configured to run against the Javascript Lite Driver. Use the following steps to configure Testkit. - -1. Clone the Testkit repository - -``` -git clone https://github.com/neo4j-drivers/testkit.git -``` - -2. Under the Testkit folder, install the requirements. - -``` -pip3 install -r requirements.txt -``` - -3. Define some enviroment variables to configure Testkit - -``` -export TEST_DRIVER_NAME=javascript -export TEST_DRIVER_REPO= -unset TEST_DRIVER_LITE -``` - -To run test against against some Neo4j version: - -``` -python3 main.py -``` - -More details about how to use Teskit could be found on [its repository](https://github.com/neo4j-drivers/testkit/tree/4.3) - -## Testing (Legacy) - -Tests **require** latest [Boltkit](https://github.com/neo4j-contrib/boltkit) and [Firefox](https://www.mozilla.org/firefox/) to be installed in the system. - -Boltkit is needed to start, stop and configure local test database. Boltkit can be installed with the following command: - -``` -pip3 install --upgrade boltkit -``` - -To run tests against "default" Neo4j version: - -``` -./runTests.sh -``` - -To run tests against specified Neo4j version: - -``` -./runTests.sh '-e 4.2.0' -``` - -Simple `npm test` can also be used if you already have a running version of a compatible Neo4j server. - -For development, you can have the build tool rerun the tests each time you change -the source code: - -``` -gulp watch-n-test -``` - -If the `gulp` command line tool is not available, you might need to install this globally: - -``` -npm install -g gulp-cli -``` - -### Testing on windows - -To run the same test suite, run `.\runTest.ps1` instead in powershell with admin right. -The admin right is required to start/stop Neo4j properly as a system service. -While there is no need to grab admin right if you are running tests against an existing Neo4j server using `npm test`.