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
- Goal
- Table of Contents
-
Walkthrough
- 1. PR Ground Rules
- 2. Local Setup: Clone the Repository
- 3. Dependencies Setup
-
How to Run Specific Tests
- Test an Entire Component
- Test a Specific Class
- Test a Specific Method
- Coverage Test (Jacoco)
- Troubleshooting: Import Errors
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 installtypically 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
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-DskipTestsbefore making any code changes.
Build the project to install the necessary packages (takes about 16 minutes):
mvn clean install -DskipTests
# [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] ------------------------------------------------------------------------
If the build fails at a certain point, you can resume it from a specific module:
mvn clean install -rf :athenz-zts-java-client
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
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
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
Coverage Test (Jacoco)
To generate a Jacoco report alongside your test for coverage verification:
mvn test jacoco:report -pl servers/zts -Dtest=AccessTokenRequestTest
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
Then:
open servers/zts/target/site/jacoco/index.html
open /servers/zts/target/site/jacoco/com.yahoo.athenz.zts/ZTSImpl.html
And you can see based on the function:
# processJAGTokenExchangeRequest(ResourceContext, Principal, AccessTokenRequest, String, String)