Testing Packages for ZPM

Hi Developers

As you know it's very easy to publish a package to the Developers Community registry. 

But how to test it before publishing?  How to be sure that everything you introduced into module.xml is installed properly?

See the step-by-step instruction below!

In this article, we'll go through the step-by-step manual process on how to test your ZPM module.

We'll take objectscript-rest-template as an example.

1. Git clone project and open it in VSCode. 

git clone git@github.com:intersystems-community/objectscript-rest-docker-template.git

2. Run docker container with:

docker-compose up -d --build

3. Open IRIS terminal and start zpm having this:

$ docker-compose exec iris iris session iris
USER>zn "IRISAPP"

IRISAPP>zpm

zpm:IRISAPP>

4. Load the package. with this step, we will check if the resources listed in module.xml really exist. The folder /irisdev/app is listed in docker-compose as volume mapping and points to the repo folder.

zpm:IRISAPP>load /irisdev/app

[rest-template] Reload START
[rest-template] Reload SUCCESS
[rest-template] Module object refreshed.
[rest-template] Validate START
[rest-template] Validate SUCCESS
[rest-template] Compile START
[rest-template] Compile SUCCESS
[rest-template] Activate START
[rest-template] Configure START
[rest-template] Configure SUCCESS
[rest-template] Activate SUCCESS
zpm: IRISAPP>

5. Test the package compilation with 'package-name package' command. Check that all the logs are without errors

zpm:IRISAPP>rest-template package

6. Testing Publishing

Now if there are no errors in the package we can publish it. But before publishing it to Open Exchange and invite everyone to use, it worth checking if all the settings and after installation invokes really perform the desired installation steps.

But how to do that if the community registry is prohibited for direct publishing?  - The answer is - to publish the package in a test registry and then deploy it with another pm client.

You can setup your own registry (here is how) and change the registry for zpm with the command:

zpm:IRISAPP>repo -n registry -r -url http://your-server:52773/registry/ -user username -pass password

To make things easier we set up a public test registry server where you are able to publish packages:

zpm:IRISAPP>repo -n registry -r -url https://test.pm.community.intersystems.com/registry/ -user test -pass PassWord42

Then call publish:

zpm: IRISAPP>rest-template publish   

[rest-template] Reload START
[rest-template] Reload SUCCESS
[rest-template] Module object refreshed.
[rest-template] Validate START
[rest-template] Validate SUCCESS
[rest-template] Compile START
[rest-template] Compile SUCCESS
[rest-template] Activate START
[rest-template] Configure START
[rest-template] Configure SUCCESS
[rest-template] Activate SUCCESS
[rest-template] Package START
Module exported to:
        /tmp/diraGF1Ui/rest-template-1.0.6/

Module package generated:
        /tmp/diraGF1Ui/rest-template-1.0.6.tgz
[rest-template] Package SUCCESS
[rest-template] Register START
[rest-template] Register SUCCESS
[rest-template] Publish START
[rest-template] Publish SUCCESS
zpm: IRISAPP>

And you can check if the app is in the registry.

zpm: IRISAPP>search

registry https://test.pm.community.intersystems.com/registry/:
rest-template                       1.0.6
zpm: IRISAPP>

7. Testing  Deployment

Here we need to take clear IRIS instance with ZPM, install the module and see if everything works as you planned. Where to take a clear IRIS instance? - start a new docker container! 

E.g.:

$ docker run --name my-iris -d --publish 9091:51773 --publish 9092:52773 intersystemsdc/irishealth-community:2020.2.0.196.0-zpm

open terminal  and start zpm:

$ docker exec -it my-iris iris session IRIS

USER>zpm

zpm: USER>

Change the repository to a test one:

zpm: USER>repo -n registry -r -url https://test.pm.community.intersystems.com/registry/ -user test -pass PassWord42

pm: IRISAPP>search

registry https://test.pm.community.intersystems.com/registry/:
rest-template                       1.0.6

Install the package:

zpm: IRISAPP>install rest-template

[rest-template] Reload START
[rest-template] Reload SUCCESS
[rest-template] Module object refreshed.
[rest-template] Validate START
[rest-template] Validate SUCCESS
[rest-template] Compile START
[rest-template] Compile SUCCESS
[rest-template] Activate START
[rest-template] Configure START
[rest-template] Configure SUCCESS
[rest-template] Activate SUCCESS
zpm: IRISAPP

Check if the application works.

In our case open browser at localhost:9092/crud/_spec and see that it was installed and works.

After that you are good to submit your application to Open Exchange and have your module published in community registry: pm.community.intersystems.com and available to everyone! Don't forget to check the "Package manager" checkbox ;)

Happy coding!