Home

Awesome

stamp-webservices

Required Tools

Configuring the system

While many parameters can be passed on the command line to the server, it is recommended to utilize config/application.json to store the properties of the system. An example file config/application-example.json is provided to give an idea of the flavor of configuration.

Users file

By default if basic authentication is used, a file config/users.json is leveraged to obtain user information. This file can be located anywhere and set using the --password_file argument on server startup. The file is expected to be a simple JSON array of users defined as a (id,username,password).

Initialize Database Tables

The database tables reflecting the schema of the application are available in the script "create-tables.sql". You should be able to execute this against a new schema and it will create all the tables, constraints and triggers necessary.

Logging

The following are the logger names supports by stamp-webservices

The logging levels can be set for both the tests and server at execution time with a command line argument. The format is as follows:

--[loggerName]_level [all|error|warn|info|debug|trace]

As well, a small web-service is available to toggle this on the fly under the path /config/loggers/[loggerName]?level=debug

You can disable any console logging using the parameter

 --silenceConsole

Executing Tests

The tests use jest to execute. The tests are designed to exercise the REST API end point so must be run in a serial fashion.
Since stamp models can be dependent on other models and create foreign key references in the database, we can only run one test at a time. This can be done with jest with the --runInBand flag. To execute the tests run

npm test

Or if create a Jest runner in your IDE be sure to add the --runInBand flag.

Some of the tests (especially the web-service tests) may take longer than the 5000ms maximum time that jest imposes by default to execute a test and commit done. The test timeout is set in the jest.config.js file to 10000 (10s) by default. This can be set on the command line with

jest --runInBand --testTimeout 25000 --sql_level error

In the above example we also set the sql logger to error instead of info level.

By default, the integration tests will look for a database in application.json called "test".
This can be overridden using the test_database parameter. The parameters recognized by the integration tests include:

Running the Server

The server uses a clustered domain to execute multiple threads bound to the same TCPIP port. By default the server will start on thread per OS reported CPU. This can be overridden at startup using the --cpu flag described below.

Executing a single threaded server (useful for testing/debugging etc.)

To execute the single threaded server, run the following command:

Executing the multi-threaded cluster server

The following are the supported options:

Configuring HTTPS

Obtain a certificate for your application. Edit the file config/application.json and add the section "Certificates" with child key values of "CertificateFile" and "CertificateKeyFile" both pointing to the location of the .crt and .key files respectfully. The server will automatically startup in HTTPS mode unless the flag "--httpOnly" has been set.

See application-example.json for the configuration format.

Code Coverage

The code coverage will be reported in the coverage folder in the project root. These values will be unreliable due to the nature of the tests execute rest APIs against a forked server process initialized for each test. Since the server process is not running in the jest process stack it does not get picked up for code coverage purposes.

Execution in CI and Jenkins

To run the tests in CI, the server must be accessible to the Jenkins process. If an environment variable is set for port this will be used to connect to the server with HTTP API requests.

Troubleshooting

MySQL 8+ Changes and Impacts