Skip to content

Latest commit

 

History

History
114 lines (73 loc) · 4.96 KB

CONTRIBUTING.md

File metadata and controls

114 lines (73 loc) · 4.96 KB
Raw

This guide provides instructions on developing and testing changes to this project.

First, before doing anything, run:

npm install

Running the default Koop server for ad hoc testing

If you'd like to do some manual ad hoc testing, you should first clone the marklogic-geo-data-services project and read the CONTRIBUTING guide there for instructions on deploying the examples/sample-project application. That application installs an app server in your MarkLogic instance on port 8095. You can then run the default Koop server (which does not require any authentication):

npm start

This will expose a Koop server at http://localhost:80 .

Running the automated tests

The tests for this project are located in a Gradle project in the ./test directory. These tests are expected to run against the test application that is deployed by the marklogic-geo-data-services project. So you'll first need to follow the CONTRIBUTING guide for that repository in order to deploy the test application in that repository.

These tests depend on hitting 2 different Koop servers:

  1. A Koop server on port 8090 that doesn't require authentication.
  2. A Koop server on port 8091 that requires MarkLogic-based authentication.

To run the tests with both Koop servers active, do the following:

cd test
./gradlew runKoopServers test

You can also run these tests from Intellij. You'll need to run the Koop servers manually. For most of the tests, run this first from the root project directory so that you have a Koop server that doesn't require auth and points to port 8096 in your MarkLogic instance:

npm run start-for-tests

Testing the provider locally

The ./examples/local-publish-testing project can be used to test publishing this project's npm package to a local registry and then using it in an example project built with [the Koop CLI](https://koopjs.github. io/docs/basics/quickstart).

You'll first need a local npm registry. For that, install verdaccio:

npm install -g verdaccio

Then run it:

verdaccio

You can go to http://localhost:4873 to verify that it's running correctly. And you'll need to follow the first instruction there, which is to add a user:

npm adduser --registry http://localhost:4873

You can add any username/password you want, and the email does not need to be a real address.

Now, publish this project's npm package to the local verdaccio registry (it's okay if you forget to specify the registry; the operation will fail because you're not authorized to publish to the real npm):

npm publish --registry http://localhost:4873

After doing so, http://localhost:4873/-/web/detail/@koopjs/provider-marklogic should now show the package that you just published.

You can now run the local-publish-testing project. You'll first need to install the Koop CLI if you have not already:

npm install -g @koopjs/cli

Now run the local-publish-testing project using the Koop CLI and the package you just published locally:

cd examples/local-publish-testing
npm install
koop serve

This should launch a Koop server on port 8080. You can verify this via the following URLs:

Testing the application zip

The "Installation Guide" in this project's docs directory describes how a user can download a versioned application zip to use as a starting point for running a Koop server with the MarkLogic Koop provider in it. You can build and test this zip locally via the following steps:

  1. Run npm pack . This will produce a koopjs-provider-marklogic-(version).tgz file in the root of this project.
  2. Extract the file, which will create a package directory (which is gitignore'd).

Then, follow the rest of the steps in the Installation Guide to configure and run the application.

Testing the documentation locally

The docs for this project are stored in the ./docs directory as a set of Markdown files. These are published via GitHub Pages using the configuration found under "Settings / Pages" in this repository.

You can build and test the docs locally by following these GitHub instructions, though you don't need to perform all of those steps since some of the files generated by doing so are already in the ./docs directory. You just need to do the following:

  1. Install the latest Ruby (rbenv works well for this).
  2. Install Jekyll.
  3. Go to the docs directory - cd ./docs .
  4. Run bundle install (this may not be necessary due to Gemfile.lock being in version control).
  5. Run bundle exec jekyll serve.

You can then go to http://localhost:4000 to view the docs.