Build

The @PLUGIN@ plugin can be built in-tree in Gerrit's /plugins path.

The plugins/external_plugin_deps.bzl file will need to be updated to match or contain @PLUGIN@/external_plugin_deps.bzl.

git clone --recursive https://gerrit.googlesource.com/gerrit
cd gerrit
git clone "https://gerrit.googlesource.com/plugins/@PLUGIN@" plugins/@PLUGIN@
ln -sf plugins/@PLUGIN@/external_plugin_deps.bzl plugins/.
bazelisk build plugins/@PLUGIN@

The output is created in

gerrit/bazel-bin/plugins/@PLUGIN@/@PLUGIN@.jar

The @PLUGIN@ plugin requires the global-refdb libModule to be available in the site/lib directory. Instructions for building the global-refdb libModule can be found here.

Eclipse project setup

This project can be imported into the Eclipse IDE:

Add the plugin name to the CUSTOM_PLUGINS_TEST_DEPS set in Gerrit core in tools/bzl/plugins.bzl,
execute:

./tools/eclipse/project.py

Run tests

The tests require a spanner service where the refdb will be created. The spanner service may be a real spanner service in GCP or a locally running docker based emulator.

Running tests using a real spanner service

In this case we have to provide an GCP service account key and the instance name under which the test refdb will be found or created. This is done by passing two environment variables GOOGLE_APPLICATION_CREDENTIALS and SPANNER_INSTANCE.

If SPANNER_DATABASE environment variable is also specified, then a database with that name will be used for testing. If a database with that name does not exist it will be created. This database will not be dropped when the test run finishes, leaving it ready for a next test run. Using this option is recommended as database creation and especially schema initialization is known to take a very long time.

If SPANNER_DATABASE environment variable is not specified then a new database will be created for this test run and will be dropped when the test run finishes.

bazelisk test \
  --test_env='GOOGLE_APPLICATION_CREDENTIALS=/path/to/the/key.json' \
  --test_env='SPANNER_INSTANCE=test-instance' \
  [--test_env='SPANNER_DATABASE=test-global-refdb'] \
  --test_tag_filters=@PLUGIN@ //...

Note that instead of using the --test_tag_filters=@PLUGIN@ //... we can also pass a different test target //plugins/@PLUGIN@/...:

bazelisk test \
  --test_env='GOOGLE_APPLICATION_CREDENTIALS=/path/to/the/key.json' \
  --test_env='SPANNER_INSTANCE=test-instance' \
  [--test_env='SPANNER_DATABASE=test-global-refdb'] \
  //plugins/@PLUGIN@/...

Running tests using a local docker based spanner emulator

This use case requires docker to be installed and running on the machine running the tests. A container running spanner will be created automatically by the tests.

The absence of the GOOGLE_APPLICATION_CREDENTIALS env variable means that the tests will create local spanner emulator.

bazelisk test //plugins/@PLUGIN@/...

MacOS specifics when using docker based spanner emulator

On MacOS you may need to access the docker daemon via TCP.

Run socat to expose the docker daemon socket via TCP

socat TCP-LISTEN:2375,fork UNIX-CONNECT:/var/run/docker.sock

Execute the tests over TCP

bazelisk test --test_env='DOCKER_HOST=tcp://127.0.0.1:2375' //plugins/@PLUGIN@/...

Debugging tests

bazelisk test --test_output=streamed //plugins/@PLUGIN@/...

If necessary increase log levels in src/test/resources/log4j.properties to trace testcontainers and docker java API.

Tracing traffic to docker daemon

If you face issue you can trace traffic to the docker daemon using socat exposing the docker daemon via TCP.

Run socat to log diagnostics and show the traffic to the docker daemon

socat -dd -v TCP-LISTEN:2375,fork UNIX-CONNECT:/var/run/docker.sock

Execute the tests over TCP

bazelisk test --test_env='DOCKER_HOST=tcp://127.0.0.1:2375' //plugins/@PLUGIN@/...

Back to @PLUGIN@ documentation index