Some Text To Go Here!

This guide provides step-by-step instructions for setting up your environment, downloading and installing an appropriate Temurin JDK 17 binary, configuring environment variables, and building the Corretto Arctic project from the command line.

• A Git client installed on your system.
• Administrative privileges (where necessary).

To get started, clone the GitHub repository to your local machine. Open a terminal and run:

git clone https://github.com/corretto/arctic.git
cd arctic

This command downloads the repository and navigates into the arctic directory.

The Temurin JDK 17 binary needs to be installed for your platform. Below are instructions for Linux, Windows, and macOS.

curl -L -o temurin.tar.gz "https://api.adoptium.net/v3/binary/latest/17/ga/linux/x64/jdk/hotspot/normal/eclipse"
tar -xzf temurin.tar.gz
mv jdk-* temurin-jdk17

Invoke-WebRequest -Uri "https://api.adoptium.net/v3/binary/latest/17/ga/windows/x64/jdk/hotspot/normal/eclipse" -OutFile "temurin.zip"
Expand-Archive -Path "temurin.zip" -DestinationPath "temurin-jdk17"

curl -L -o temurin.tar.gz "https://api.adoptium.net/v3/binary/latest/17/ga/mac/x64/jdk/hotspot/normal/eclipse"
tar -xzf temurin.tar.gz
mv jdk-* temurin-jdk17

In the shell, set the environment variables for JAVA_HOME & PATH

export JAVA_HOME=$(pwd)/temurin-jdk17
export PATH=$JAVA_HOME/bin:$PATH

Apply the changes:

source ~/.bashrc  # or source ~/.zshrc

$env:JAVA_HOME = "$(Get-Location)\temurin-jdk17"
$env:Path += ";$env:JAVA_HOME\bin"

To make these changes permanent, update the system environment variables manually:

1. Open System Properties > Advanced > Environment Variables.
2. Add a new variable JAVA_HOME pointing to the extracted temurin-jdk17 folder.
3. Append %JAVA_HOME%\bin to the Path variable.

Confirm that the correct JDK version is installed:

java -version

The output should indicate JDK 17 from Eclipse Temurin:

openjdk version "17.0.x" 202x-xx-xx

Navigate to the project root directory:

cd ..  # Move to the project root

Run the Gradle build command:

./gradlew build  # Linux/macOS

.\gradlew.bat build  # Windows

This will download dependencies and build the project.

You have successfully cloned the repository, installed the Temurin JDK 17, set up environment variables, and built the project using Gradle. The built Arctic.jar should be in the build/Jars subdirectory of the base arctic directory.

Arctic depends on com.github.kwhat:jnativehook:2.2.2 for global keyboard and mouse capture. The pre-built JAR from Maven Central does not include a Windows ARM64 native DLL, so it must be compiled from source and substituted into the Arctic fat-JAR before use on ARM64 machines.

Run all commands in Windows Command Prompt (cmd.exe), not PowerShell or Cygwin. CMake's Visual Studio generator does not work correctly from PowerShell or MSYS shells.

In addition to the standard prerequisites above, install:

Verify the environment before starting:

java -version
mvn -version
git --version
where cmake
cmake --version
cmake --help | findstr /i "Visual Studio"

Confirm that cmake --help lists Visual Studio 17 2022 as an available generator and that where cmake returns a path under Program Files\CMake, not Cygwin or MSYS2.

Set the environment for the current session (adjust paths to your installations):

set "JAVA_HOME=C:\Tools\jdk-17"
set "PATH=%JAVA_HOME%\bin;C:\Tools\apache-maven\bin;C:\Program Files\CMake\bin;%PATH%"

mkdir C:\arctic-dev\jnativehook
cd /d C:\arctic-dev\jnativehook
git clone --branch 2.2 https://github.com/kwhat/jnativehook.git
cd jnativehook

Initialise the libuiohook submodule using HTTPS (avoids needing an SSH key):

git submodule init
git config submodule.libuiohook.url https://github.com/kwhat/libuiohook.git
git submodule update --init --recursive

Verify the submodule is present:

dir src\external\libuiohook\CMakeLists.txt

Use a full git clone, not a source ZIP. The ZIP does not include the submodule and the build will fail at the CMake configure step.

mvn clean compile

Confirm the generated header exists:

dir target\include\com_github_kwhat_jnativehook_GlobalScreen.h

Edit the root CMakeLists.txt. Find the target_include_directories(jnativehook ...) block and replace it with the following to add the Maven-generated header directory:

target_include_directories(jnativehook
    PUBLIC
        $<BUILD_INTERFACE:${JNI_INCLUDE_DIRS}>

    PRIVATE
        ${CMAKE_CURRENT_SOURCE_DIR}/src/main/jni
        ${CMAKE_CURRENT_SOURCE_DIR}/src/main/jni/include
        "${CMAKE_CURRENT_SOURCE_DIR}/target/include"
)

Do not run mvn clean again after this point. It deletes target\, removing the native build outputs and generated JNI headers. Use mvn compile if you only need to regenerate headers.

Run each command from the repository root as a single line:

cmake -S src/external/libuiohook -B target/build/libuiohook-arm64 -G "Visual Studio 17 2022" -A ARM64 "-DCMAKE_INSTALL_PREFIX=%CD%/target/native-arm64" -DBUILD_SHARED_LIBS=OFF

cmake --build target/build/libuiohook-arm64 --config RelWithDebInfo --parallel 2

cmake --install target/build/libuiohook-arm64 --config RelWithDebInfo

This compiles libuiohook as a static library that will be linked into the DLL.

cmake -S . -B target/build/jni-arm64 -G "Visual Studio 17 2022" -A ARM64 "-DCMAKE_PREFIX_PATH=%CD%/target/native-arm64" -DCMAKE_SYSTEM_NAME=Windows -DCMAKE_SYSTEM_PROCESSOR=arm64

cmake --build target/build/jni-arm64 --config RelWithDebInfo --parallel 2

cmake --install target/build/jni-arm64 --config RelWithDebInfo

The compiled DLL is at:

C:\arctic-dev\jnativehook\jnativehook\target\build\jni-arm64\RelWithDebInfo\JNativeHook.dll

The install step also copies it to the JAR resource path:

C:\arctic-dev\jnativehook\jnativehook\src\main\resources\com\github\kwhat\jnativehook\lib\windows\arm64\JNativeHook.dll

mvn package
jar tf target\jnativehook-2.2-SNAPSHOT.jar | findstr /i "JNativeHook.dll"

The listing must include:

com/github/kwhat/jnativehook/lib/windows/arm64/JNativeHook.dll

Arctic is distributed as a single fat-JAR (Arctic.jar) that bundles jNativeHook inside it. Replace the bundled DLL with the ARM64 one you just built:

cd /d C:\arctic-dev\jnativehook\jnativehook
jar uf <path-to>\Arctic.jar -C src\main\resources .

Verify the replacement:

jar tf <path-to>\Arctic.jar | findstr /i "JNativeHook.dll"

The path com/github/kwhat/jnativehook/lib/windows/arm64/JNativeHook.dll must appear.

In order to successfully "Record" and "Playback", on some platforms require OS Permission settings to enable screen capture and mouse interaction:

• MacOS:
  • System Settings -> Privacy and Security -> Accessibility :
    • Add both "Terminal" and "Java" (selecting your jdk Contents/Home/bin/java). Then restart your machine.

1. Start "Test case" and ensure in center of the screen. Note: If you are running tests using the JTharness on Windows, that you can ensure repeatable ordered test execution for multi-tests by specifying the JVM system property -Dmultitest.testcaseOrder=sorted
2. Start Arctic "recorder" CLI

java -jar build/jars/Arctic.jar -r

3. The first time this is run it will just generate the "recording.properties" file, edit this to adjust these recommended values:

arctic.common.repository.json.path = ./arctic_tests
arctic.recorder.pre.init.timings.startDelayMs = 500
arctic.recorder.pre.init.timings.scDelayMs = 500
arctic.recorder.pre.firstSc.delay = 500

NOTE: If running from a Mac, you will probably need to change the Arctic "modifier" keys to avoid clash with Mac's suspend process cmd, eg. change to "Ctrl-Shift" (keys ref: https://github.com/kwhat/jnativehook/blob/2.2/src/main/java/com/github/kwhat/jnativehook/keyboard/NativeKeyEvent.java):

# Ctrl-Shift
arctic.recorder.control.jnh.modifiers = 29, 42

then re-run to actually start recording

4. Workbench window should now have been opened and sent to "background" behind your test case
5. Move "Shade" to the side out of "Workbench"
6. Tell Arctic CLI the group and test case name : test start mytests test1
7. Select Arctic "workbench" window as focus
8. Start recording : <Modifiers>-Z
9. Interact with test case and take screen shots at appropriate check points... : <Modifiers>-X
10. On completion of interaction, stop recording : <Modifiers>-Z
11. Quit Arctic recorder CLI : "Quit"
12. The recordings will be saved under: ./arctic_tests/default/<group_name>/<test_name>

1. Start "Test case" initial window and ensure in center of the screen
2. Start Arctic "player" CLI

java -Darctic.logLevel=TRACE -jar build/jars/Arctic.jar -p

3. The first time this is run it will just generate the "player.properties" file, edit this to adjust these recommended values:

arctic.common.repository.json.path = ./arctic_tests
# Some slower systems need lower strict pixel confidence
arctic.player.backend.sc.pixel.confidence.min = 0.5
# Fuzzy check RGB component tolerance needs relaxing slightly to be reliable
arctic.player.backend.sc.pixel.fuzzy.tolerance = 12
# Screenshot delays need slight increase for slower systems
arctic.player.pre.firstTestDelay.wait = 500
arctic.player.pre.scValidator.wait.focus = 500

then re-run to actually start playback

4. Workbench window should now have been opened and sent to "background" behind your test case
5. Tell Arctic CLI to start "playing" your group and test case : test start mytests test1
6. Arctic will now interact in "real time" with the test case window using the recordings and verify the screenshots
7. If all is successful Arctic CLI will output the following. "Unconfirmed" means no manual human check has been performed on the playback:

FINISHED: mytests:test1 with UNCONFIRMED

8. To manually confirm the test run, type command:

test finish mytests test1 true

9. If some error/failure/missmatch has occurred during playback message like the following will appear:

FINISHED: mytests:test1 with ABORTED

In this situation you can debug the problem using the "sc review" command in the CLI, this will open the failed screen review window, pressing the ">>" icon repeatedly can be used to visually see what differs between the "current" image and the "recorded" image. If the additional bottom left checkboxes are enabled, you can view the "strict/fuzzy/cluster" difference images which will show the areas that fail the "strict/fuzzy/cluster" comparison, the top row checkboxes can also be enabled to show "strict/fuzzy/cluster" "hints":

10. Quit Arctic recorder CLI : "Quit"
11. The failed playback images are saved to folder failures/mytests/test1

The Arctic CLI can be started in local RMI mode using local loopback RMI, this enables CLI commands to be posted via RMI to the CLI.

To enable RMI local mode only:

1. Edit player.properties:

arctic.common.repository.json.path = ./arctic_tests
arctic.common.cmd.rmi.enabled = local_only
arctic.common.cmd.console.enabled = false  # NOTE: missing ".enabled" in default property name!
arctic.player.confirmation.mode = false    # Test passes after successful playback without need for manual "confirmation"

arctic.player.confirmation.mode must be "false" if no async confirmation detection is being performed, ie. Arctic post-processing will commence after the playback has completed with status being "UNCONFIRMED".

arctic.player.confirmation.mode must be "true" if async confirmation detection is being performed, eg. via a test harness "observer" which sends a "test finish" command. Arctic processing will remain "RUNNING"/"STARTING" until async observer confirmation has been received, after which the status will become "CONFIRMED" and post-processing then completes.

2. Script to playback an example "mytests/test1":

testgroup="mytests"
testcase="test1"

echo "Starting player in background with RMI..."
java -Darctic.logLevel=TRACE -jar build/jars/Arctic.jar -p &
rc=$?
if [[ $rc -ne 0 ]]; then
   echo "Unable to start Arctic player, rc=$rc"
   exit $rc
fi

# Allow 3 seconds for RMI server to start...
sleep 3

java -jar build/jars/Arctic.jar -c test start "${testgroup}" "${testcase}"
rc=$?
if [[ $rc -ne 0 ]]; then
   echo "Unable to start playback for testcase ${testgroup}/${testcase}, rc=$rc"
   exit $rc
fi

sleep 3
result=$(java -jar build/jars/Arctic.jar -c test list ${testgroup}/${testcase})
rc=$?
status=$(echo $result | tr -s ' ' | cut -d' ' -f2)
echo "==>" $status
while [[ $rc -eq 0 ]] && { [[ "$status" == "RUNNING" ]] || [[ "$status" == "STARTING" ]]; };
do
  sleep 3
  result=$(java -jar build/jars/Arctic.jar -c test list ${testgroup}/${testcase})
  rc=$?
  status=$(echo $result | tr -s ' ' | cut -d' ' -f2)
  echo "==>" $status
done

echo "Terminating Arctic CLI..."
java -jar build/jars/Arctic.jar -c terminate

echo "Completed playback of ${testgroup}/${testcase} status: ${status}"

Some useful tips:

1. Debugging can be controlled by passing property "-Darctic.logLevel=TRACE|DEBUG" to the java process. Log output will then output to the Java process stdout/err.
2. Make sure recording and playback processes are using the same version of Java, otherwise image encoding may differ.
3. Display settings need to match between recording and playback, eg. screen size and OS visual enhancements, for example:
   • On MacOS, disable "True Tone"
4. VNC session "mouse pointer" can cause failures due to mouse artifact in the recording, seems intermittent, just re-record when it happens.
5. On "Linux" intermittent X11 AWT "hangs" are seen during playback when "re-size" window operations are recorded, ie. right-click on resize title bar icon & drag operations. So avoid re-sizing windows on Linux recordings, try and use original window size.