Skip to content

Arctic Project Guide

Jump to bottom
Andrew Leonard edited this page Mar 19, 2025 · 10 revisions
Section 1: Introduction

Some Text To Go Here!

Section 2: Installation

Setting Up and Building the Corretto Arctic Project

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.

Prerequisites

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

Step 1: Clone the Repository

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.

Step 2: Download and Install Temurin JDK 17

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

Linux

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

Windows (PowerShell)

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"

macOS

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

Step 3: Configure Environment Variables

Linux/macOS

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

Windows (PowerShell)

$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.

Step 4: Verify Java Installation

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

Step 5: Build the Project with Gradle

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.

Conclusion

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

Section 3: Configuration

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.
Section 4: Recording A Test
  1. Start "Test case" and ensure in center of the screen
  2. Start Arctic "recorder" CLI
java -jar build/jars/Arctic.jar -r
  1. Workbench window should now have been opened and sent to "background" behind your test case
  2. Move "Shade" to the side out of "Workbench"
  3. Tell Arctic CLI the group and test case name : test start mytests test1
  4. Select test case window as focus
  5. Start recording : Ctrl-Alt-Z
  6. Interact with test case and take screen shots at appropriate check points... : Ctrl-Alt-X
  7. On completion of interaction, stop recording : Ctrl-Alt-Z
  8. Quit Arctic recorder CLI : "Quit"
  9. The recordings will be saved under: ../arctic_tests/default/<group_name>/<test_name>
Section 5: Playing Back A Test Manually (non-RMI mode)
  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
  1. Workbench window should now have been opened and sent to "background" behind your test case
  2. Tell Arctic CLI to start "playing" your group and test case : test start mytests test1
  3. Arctic will now interact in "real time" with the test case window using the recordings and verify the screenshots
  4. 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
  1. To manually confirm the test run, type command:
test finish mytests test1 true
  1. 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":

Screenshot 2025-03-19 at 10 00 52

  1. Quit Arctic recorder CLI : "Quit"
  2. The failed playback images are saved to folder "failures/mytests/test1"
Section 6: Playing Back A Test via Scripting or RMI mode

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.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"
  1. 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}"
Section 7: Troubleshooting Tips & Tricks

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"
Clone this wiki locally