DEV Community

Jeongwoo Kim
Jeongwoo Kim

Posted on

[Hands-on] Guide to Locally Testing Athenz Before Opening a PR

#athenz #testing #opensource

Goal

This post provides a guide on how to run unit tests locally before submitting a Pull Request (PR) to the Athenz repository.

Prerequisite: You must have a local development environment (Java, Maven, etc.) configured to build and run Athenz.

Table of Contents

Walkthrough

The following steps outline the process for setting up and testing Athenz locally.

1. PR Ground Rules

Please review the following repository rules before submitting a PR:

  • Use [skip ci]: If your changes do not require CI testing (e.g., documentation updates or typo fixes), add [skip ci] to your PR title to save CI resources. (Reference)
  • Pass formatting checks: You must pass code formatting tests before creating a PR. Running mvn clean install typically handles this. (Reference)

2. Local Setup: Clone the Repository

Clone the official Athenz repository and navigate into the directory:

git clone [https://github.com/AthenZ/athenz.git](https://github.com/AthenZ/athenz.git) && cd athenz
Enter fullscreen mode Exit fullscreen mode

3. Dependencies Setup

[!NOTE]
Running an initial build without this flag may cause test failures due to missing dependencies. It is recommended to run a full install with -DskipTests before making any code changes.

Build the project to install the necessary packages (takes about 16 minutes):

mvn clean install -DskipTests
Enter fullscreen mode Exit fullscreen mode 
# [INFO] ------------------------------------------------------------------------
# [INFO] Reactor Summary for AthenZ 1.12.43-SNAPSHOT:
# [INFO]
# [INFO] AthenZ ............................................. SUCCESS [ 11.612 s]
# [INFO] rdl-gen-athenz-server .............................. SUCCESS [  1.734 s]
# [INFO] rdl-gen-athenz-go-model ............................ SUCCESS [  1.178 s]
# [INFO] rdl-gen-athenz-go-client ........................... SUCCESS [  1.020 s]
# [INFO] rdl-gen-athenz-java-model .......................... SUCCESS [  1.125 s]
# [INFO] rdl-gen-athenz-java-client ......................... SUCCESS [  1.179 s]
# [INFO] athenz-zms-core .................................... SUCCESS [  7.690 s]
# [INFO] athenz-zts-core .................................... SUCCESS [  5.397 s]
# [INFO] athenz-msd-core .................................... SUCCESS [  4.993 s]
# [INFO] athenz-auth-core ................................... SUCCESS [  4.309 s]
# [INFO] athenz-client-common ............................... SUCCESS [  1.637 s]
# [INFO] athenz-cert-refresher .............................. SUCCESS [  1.690 s]
# [INFO] athenz-zms-java-client ............................. SUCCESS [  5.229 s]
# [INFO] athenz-zts-java-client ............................. SUCCESS [  5.206 s]
# [INFO] athenz-server-common ............................... SUCCESS [  5.874 s]
# [INFO] athenz-k8s-server-common ........................... SUCCESS [  1.562 s]
# [INFO] athenz-dynamodb-client-factory ..................... SUCCESS [  1.559 s]
# [INFO] athenz-syncer-common ............................... SUCCESS [  1.866 s]
# [INFO] athenz-aws-server-common ........................... SUCCESS [  3.624 s]
# [INFO] athenz-server-gcp-common ........................... SUCCESS [  3.046 s]
# [INFO] athenz-instance-provider ........................... SUCCESS [  3.109 s]
# [INFO] athenz-server-msg-pulsar ........................... SUCCESS [  2.337 s]
# [INFO] athenz-server-notification-slack ................... SUCCESS [  2.014 s]
# [INFO] athenz-zpe-java-client ............................. SUCCESS [  1.906 s]
# [INFO] athenz-msd-java-client ............................. SUCCESS [  4.454 s]
# [INFO] athenz-gcp-zts-creds ............................... SUCCESS [  1.841 s]
# [INFO] athenz-zms-server .................................. SUCCESS [ 11.515 s]
# [INFO] athenz-zts-server .................................. SUCCESS [ 16.613 s]
# [INFO] athenz-jetty-container ............................. SUCCESS [  2.593 s]
# [INFO] athenz-auth-history-syncer ......................... SUCCESS [  5.755 s]
# [INFO] athenz-zms-aws-domain-syncer ....................... SUCCESS [  2.542 s]
# [INFO] athenz-zms-gcp-domain-syncer ....................... SUCCESS [  2.743 s]
# [INFO] zms-go-client ...................................... SUCCESS [ 28.624 s]
# [INFO] zts-go-client ...................................... SUCCESS [  2.974 s]
# [INFO] msd-go-client ...................................... SUCCESS [  2.936 s]
# [INFO] sia-go-lib ......................................... SUCCESS [01:49 min]
# [INFO] zmscli ............................................. SUCCESS [  3.878 s]
# [INFO] zmssvctoken ........................................ SUCCESS [ 13.350 s]
# [INFO] ztsclientutil ...................................... SUCCESS [  2.409 s]
# [INFO] athenzconf ......................................... SUCCESS [  1.288 s]
# [INFO] usercert ........................................... SUCCESS [  9.949 s]
# [INFO] sia-aws-ec2 ........................................ SUCCESS [04:15 min]
# [INFO] sia-aws-eks ........................................ SUCCESS [ 22.090 s]
# [INFO] sia-aws-fargate .................................... SUCCESS [  9.466 s]
# [INFO] sia-azure-vm ....................................... SUCCESS [  4.781 s]
# [INFO] sia-build-kite ..................................... SUCCESS [ 12.964 s]
# [INFO] sia-gcp-gce ........................................ SUCCESS [ 52.004 s]
# [INFO] sia-gcp-gke ........................................ SUCCESS [ 21.204 s]
# [INFO] sia-gcp-run ........................................ SUCCESS [ 20.085 s]
# [INFO] sia-github-actions ................................. SUCCESS [  5.740 s]
# [INFO] sia-harness ........................................ SUCCESS [  5.529 s]
# [INFO] sia-spacelift ...................................... SUCCESS [ 20.759 s]
# [INFO] zms-cli ............................................ SUCCESS [  3.165 s]
# [INFO] athenz-conf ........................................ SUCCESS [  1.306 s]
# [INFO] zms-domainattrs .................................... SUCCESS [  3.052 s]
# [INFO] zms-svctoken ....................................... SUCCESS [  2.400 s]
# [INFO] zms-authhistory .................................... SUCCESS [  2.145 s]
# [INFO] zpe-updater ........................................ SUCCESS [  4.181 s]
# [INFO] zts-roletoken ...................................... SUCCESS [  2.008 s]
# [INFO] zts-accesstoken .................................... SUCCESS [  2.019 s]
# [INFO] zts-idtoken ........................................ SUCCESS [  2.062 s]
# [INFO] zts-rolecert ....................................... SUCCESS [  3.681 s]
# [INFO] zts-svccert ........................................ SUCCESS [  2.051 s]
# [INFO] zts-svctoken ....................................... SUCCESS [  2.121 s]
# [INFO] zts-usercert ....................................... SUCCESS [  2.019 s]
# [INFO] msd-agent .......................................... SUCCESS [  3.766 s]
# [INFO] athenz-auth-core-nodejs ............................ SUCCESS [ 40.861 s]
# [INFO] athenz-zts-nodejs-client ........................... SUCCESS [ 13.504 s]
# [INFO] athenz-zpe-nodejs-client ........................... SUCCESS [ 15.892 s]
# [INFO] ui ................................................. SUCCESS [ 58.317 s]
# [INFO] athenz-zms ......................................... SUCCESS [  6.516 s]
# [INFO] athenz-zts ......................................... SUCCESS [  7.730 s]
# [INFO] athenz-ui .......................................... SUCCESS [ 44.331 s]
# [INFO] athenz-utils ....................................... SUCCESS [ 12.492 s]
# [INFO] ------------------------------------------------------------------------
# [INFO] BUILD SUCCESS
# [INFO] ------------------------------------------------------------------------
# [INFO] Total time:  16:10 min
# [INFO] Finished at: 2026-06-13T17:59:23+09:00
# [INFO] ------------------------------------------------------------------------
Enter fullscreen mode Exit fullscreen mode

If the build fails at a certain point, you can resume it from a specific module:

mvn clean install -rf :athenz-zts-java-client
Enter fullscreen mode Exit fullscreen mode

How to Run Specific Tests

Athenz contains a large test suite. Below are the commands to run specific segments of the tests based on your needs.

Test an Entire Component

To test a whole server module (e.g., zts or zms), use the following command:

mvn test -pl servers/zts
Enter fullscreen mode Exit fullscreen mode

Test a Specific Class

To test a specific class file, use the -Dtest option:

mvn test -pl servers/zts -Dtest=AccessTokenRequestTest
mvn test -pl servers/zts -Dtest=ZTSImplAccessTokenTest
Enter fullscreen mode Exit fullscreen mode

Test a Specific Method

To test a single method within a class, use # to specify the method name:

mvn test -pl servers/zts -Dtest=AccessTokenRequestTest#testAccessTokenRequestJWTBearer
Enter fullscreen mode Exit fullscreen mode

Coverage Test (Jacoco)

To generate a Jacoco report alongside your test for coverage verification:

mvn test jacoco:report -pl servers/zts -Dtest=AccessTokenRequestTest
Enter fullscreen mode Exit fullscreen mode

Troubleshooting: Import Errors

Todo: This section is a work in progress and will cover common IDE import errors and resolution steps.

mvn clean test jacoco:report -pl servers/zts -Dtest=ZTSImplAccessTokenTest
Enter fullscreen mode Exit fullscreen mode

Then:

open servers/zts/target/site/jacoco/index.html
open /servers/zts/target/site/jacoco/com.yahoo.athenz.zts/ZTSImpl.html
Enter fullscreen mode Exit fullscreen mode

And you can see based on the function:

# processJAGTokenExchangeRequest(ResourceContext, Principal, AccessTokenRequest, String, String)
Enter fullscreen mode Exit fullscreen mode

Top comments (0)