Proton Test Script

The Proton test script (ptest) can help diagnose Proton connection issues. Although ptest is embedded in the domino-db package, it doesn't require any programming. You simply use npm to install the package. Then you can execute ptest commands to verify your connection to Proton.

Prerequisites

• Node.js.
• A Domino server with the Proton add-in.
• The domino-db archive file (domino-domino-db-1.11.0.tgz).

Installation

Expand the domino-db archive and install it. You can expand the archive to a folder of your choice. The following example assumes the archive is in your home directory. It expands the archive to a sub-folder called domino-db:

cd ~
mkdir domino-db
cd domino-db
tar xvf ../domino-domino-db-1.11.0.tgz
cd package
npm install

General usage

Usage: npm run ptest -- <command> [...]

where <command> is one of:
  connect, help, or read

For help on a specific command:
  npm run ptest -- <command> -h

Connect command

Usage: npm run ptest -- connect <host>[:<port>]

where <host> specifies a server host name and <port> specifies
the Proton port. If <port> is omitted the default is 3002.

Examples:
  npm run ptest -- connect localhost
  npm run ptest -- connect server.com:3003

The connect command require a target server. For example, the following command connects to port 3004 on localhost:

[~/domino-db/package]$ npm run ptest -- connect localhost:3004

> @domino/domino-db@1.1.11 ptest /home/user/domino-db/package
> node proton-test/bin/ptest "connect" "localhost:3004"

Resolving localhost ...
localhost resolved.
Testing connection to localhost:3004 ...
Successfully connected to localhost:3004.

The connect command succeeds when it is able to connect to the specified port and host. This does not, by itself, prove it's Proton listening on the port. Nor does it prove you are able to authenticate with Proton. Use the read command to further verify your connection.

Read command

Usage: npm run ptest -- read <server>/<db> <options>

where <server> specifies a server, <db> specifies a database on the
server, and <options> include:
  -a            abort on first error
  -c <count>    maximum number of documents to read
  -i <items>    read the items in the comma separated list of item names
  -p            pretty JSON output
  -q <query>    read documents matching the query
  -s <start>    index of first document to read
  -u <unids>    read documents in the comma separated list of UNIDs

Examples:
  npm run ptest -- read localhost:3003/your.nsf -q "Form = 'Contact' and LastName = 'Smith'"
  npm run ptest -- read server1/your.nsf -u F40E19AED2E346BE852582890064471B

By default, ptest connects to the host over an insecure connection (not TLS) on port 3002. If your server's Proton add-in uses TLS, you need to configure ptest before you can use the read command. See Configuration for details.

This example reads all documents matching the query Form = 'Contact' and LastName = 'Moody' in node-demo.nsf on server localhost.

[~/domino-db/package]$ npm run ptest -- read localhost/node-demo.nsf -p -q "Form = 'Contact' and LastName = 'Moody'"

> @domino/domino-db@1.1.11 ptest /home/user/domino-db/package
> node proton-test/bin/ptest "read" "localhost/node-demo.nsf" "-p" "-q" "Form = 'Contact' and LastName = 'Moody'"

{
  "documents": [
    {
      "@unid": "A1416B681224A3EE852582DA0055D63B",
      "@created": {
        "type": "datetime",
        "data": "2018-07-30T15:37:34.03Z"
      },
      "@modified": {
        "type": "datetime",
        "data": "2018-07-30T15:37:35.01Z"
      }
    },
    {
      "@unid": "4A51270A49D9C592852582DA0055D63F",
      "@created": {
        "type": "datetime",
        "data": "2018-07-30T15:37:34.07Z"
      },
      "@modified": {
        "type": "datetime",
        "data": "2018-07-30T15:37:35.09Z"
      }
    }
  ],
  "documentRange": {
    "total": 2,
    "start": 0,
    "count": 2
  }
}

By default the read response just contains document metadata (e.g. @unid and @created). If you want to read document items, you use the -i option to specify the item names:

[~/domino-db/package]$ npm run ptest -- read localhost/node-demo.nsf -p -q "Form = 'Contact' and LastName = 'Moody'" -i FirstName,LastName,City,State

> @domino/domino-db@1.1.11 ptest /home/user/domino-db/package
> node proton-test/bin/ptest "read" "localhost/node-demo.nsf" "-p" "-q" "Form = 'Contact' and LastName = 'Moody'" "-i" "FirstName,LastName,City,State"

{
  "documents": [
    {
      "@unid": "A1416B681224A3EE852582DA0055D63B",
      "@created": {
        "type": "datetime",
        "data": "2018-07-30T15:37:34.03Z"
      },
      "@modified": {
        "type": "datetime",
        "data": "2018-07-30T15:37:35.01Z"
      },
      "FirstName": "Deana",
      "LastName": "Moody",
      "City": "Jackson",
      "State": "MS"
    },
    {
      "@unid": "4A51270A49D9C592852582DA0055D63F",
      "@created": {
        "type": "datetime",
        "data": "2018-07-30T15:37:34.07Z"
      },
      "@modified": {
        "type": "datetime",
        "data": "2018-07-30T15:37:35.09Z"
      },
      "FirstName": "Edwin",
      "LastName": "Moody",
      "City": "Toledo",
      "State": "OH"
    }
  ],
  "documentRange": {
    "total": 2,
    "start": 0,
    "count": 2
  }
}

Configuration

To configure ptest, create a .ptest folder in your home directory. Then create a config.json file in the .ptest folder.

NOTE: The location of your home directory varies from one OS to another. For examples, on Windows 10, it is usually C:\Users\{username}; on Linux, it is usually /home/{username}.

The {home}/.ptest/config.json file is used to configure access to individual servers. It is also used to configure certificates and keys for TLS connections. The following example defines two servers (server1 and server2):

{
  "servers": {
    "server1": {
      "hostName": "10.10.10.10",
      "connection": {
        "port": "3002",
        "secure": false
      }
    },
    "server2": {
      "hostName": "10.10.10.11",
      "connection": {
        "port": "3002",
        "secure": true
      },
      "credentials": {
        "rootCertificateFile": "/home/user/certs/root.crt",
        "clientCertificateFile": "/home/user/certs/client.crt",
        "clientKeyFile": "/home/user/certs/client.key"
      }
    }
  }
}

In this example:

• server1 has a host name of 10.10.10.10 and listens for insecure connections on port 3002.
• server2 has a host name of 10.10.10.11 and listens for secure connections ("secure": true) on port 3002. The ptest script uses the configured certificates and key to make the secure connection.