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 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
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-DskipTestsbefore 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
답글 남기기