Merge branch 'ci/label-exclusions' into ci/tests

Add a condition to the release workflow to skip execution if the PR
is labeled with 'Kind/Testing' or 'Kind/Documentation'. This prevents
unnecessary releases for non-functional changes.

.gitea/workflows/release.yaml

@@ -8,7 +8,10 @@ on:
 
 jobs:
   release:
-    if: github.event.pull_request.merged == true
+    if: |
+      github.event.pull_request.merged == true &&
+      !contains(github.event.pull_request.labels.*.name, 'Kind/Testing') &&
+      !contains(github.event.pull_request.labels.*.name, 'Kind/Documentation')
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code

README.md

@@ -84,22 +84,36 @@ You can define your preferred defaults in `~/.config/color-tool/config.toml`. Th
 
 ```toml
 [defaults]
-output = "hex"  # default output format(s)
+# Set any option to true to enable it by default when using the terminal
+output = "hex"  # default output format(s): hex, rgb, hsl, rgba, hsla, hexa, all
 json   = false  # output in JSON format
 swatch = false  # show color swatch in terminal
-name   = false  # fetch color name
+name   = false  # fetch color name from thecolorapi.com
 copy   = false  # copy result to clipboard
-pick   = false  # auto-launch picker
+pick   = false  # auto-launch color picker when invoked with no arguments
 notify = false  # show desktop notification
 
 [desktop]
-output = "hex"
-json   = false
-name   = false
-copy   = true
-notify = true
+# Defaults for --desktop mode (launched from the app menu; copy is always enabled by default)
+output = "hex"  # format to copy
+json   = false  # copy JSON format instead of plain text
+name   = false  # fetch color name (requires network)
+copy   = true   # copy result to clipboard
+notify = true   # show desktop notification with the copied value
 ```
 
+## 🧪 Testing
+
+The project includes a comprehensive test suite that verifies color conversion, configuration loading, and system integrations (clipboard/notifications) using mocks.
+
+To run the tests:
+
+```bash
+./tests/run_tests.sh
+```
+
+The test script creates a temporary isolated environment, so it won't affect your system configuration or active clipboard.
+
 ## 🤝 Credits
 
 The `wl-colorpicker-plasma` integration is based on the original work by [SASUPERNOVA](https://github.com/SASUPERNOVA/wl-colorpicker-plasma).

color-tool

@@ -63,7 +63,7 @@ load_config() {
 
   local section="" key val
   while IFS= read -r line; do
-    line="${line%%#*}"   # strip inline comments
+    line="${line%%#*}" # strip inline comments
     if [[ "$line" =~ ^[[:space:]]*$ ]]; then continue; fi
 
     # Section header
@@ -76,25 +76,26 @@ load_config() {
     if [[ "$line" =~ ^[[:space:]]*([A-Za-z_]+)[[:space:]]*=[[:space:]]*([^[:space:]]+) ]]; then
       key="${BASH_REMATCH[1]}"
       val="${BASH_REMATCH[2],,}"
-      val="${val#\"}" ; val="${val%\"}"
+      val="${val#\"}"
+      val="${val%\"}"
       case "$section:$key" in
-        defaults:json)   [[ "$val" == "true" ]] && json_mode=1    || json_mode=0 ;;
-        defaults:alpha)  [[ "$val" == "true" ]] && alpha_mode=1   || alpha_mode=0 ;;
-        defaults:name)   [[ "$val" == "true" ]] && name_mode=1    || name_mode=0 ;;
-        defaults:copy)   [[ "$val" == "true" ]] && copy_mode=1    || copy_mode=0 ;;
-        defaults:pick)   [[ "$val" == "true" ]] && config_pick=1  || config_pick=0 ;;
-        defaults:notify) [[ "$val" == "true" ]] && notify_mode=1  || notify_mode=0 ;;
-        defaults:swatch) [[ "$val" == "true" ]] && swatch_mode=1  || swatch_mode=0 ;;
-        defaults:output) output_formats="$val" ;;
-        desktop:json)    [[ "$val" == "true" ]] && desktop_json=1   || desktop_json=0 ;;
-        desktop:alpha)   [[ "$val" == "true" ]] && desktop_alpha=1  || desktop_alpha=0 ;;
-        desktop:name)    [[ "$val" == "true" ]] && desktop_name=1   || desktop_name=0 ;;
-        desktop:notify)  [[ "$val" == "true" ]] && desktop_notify=1 || desktop_notify=0 ;;
-        desktop:copy)    [[ "$val" == "true" ]] && desktop_copy=1   || desktop_copy=0 ;;
-        desktop:output)  desktop_output="$val" ;;
+      defaults:json) [[ "$val" == "true" ]] && json_mode=1 || json_mode=0 ;;
+      defaults:alpha) [[ "$val" == "true" ]] && alpha_mode=1 || alpha_mode=0 ;;
+      defaults:name) [[ "$val" == "true" ]] && name_mode=1 || name_mode=0 ;;
+      defaults:copy) [[ "$val" == "true" ]] && copy_mode=1 || copy_mode=0 ;;
+      defaults:pick) [[ "$val" == "true" ]] && config_pick=1 || config_pick=0 ;;
+      defaults:notify) [[ "$val" == "true" ]] && notify_mode=1 || notify_mode=0 ;;
+      defaults:swatch) [[ "$val" == "true" ]] && swatch_mode=1 || swatch_mode=0 ;;
+      defaults:output) output_formats="$val" ;;
+      desktop:json) [[ "$val" == "true" ]] && desktop_json=1 || desktop_json=0 ;;
+      desktop:alpha) [[ "$val" == "true" ]] && desktop_alpha=1 || desktop_alpha=0 ;;
+      desktop:name) [[ "$val" == "true" ]] && desktop_name=1 || desktop_name=0 ;;
+      desktop:notify) [[ "$val" == "true" ]] && desktop_notify=1 || desktop_notify=0 ;;
+      desktop:copy) [[ "$val" == "true" ]] && desktop_copy=1 || desktop_copy=0 ;;
+      desktop:output) desktop_output="$val" ;;
       esac
     fi
-  done < "$CONFIG_FILE"
+  done <"$CONFIG_FILE"
 }
 
 # ── Help ──────────────────────────────────────────────────────────────────────
@@ -159,7 +160,7 @@ copy_to_clipboard() {
   elif command -v xclip &>/dev/null; then
     printf '%s' "$text" | xclip -selection clipboard
   else
-    echo "Warning: no clipboard utility found (install wl-copy or xclip)" >&2
+    echo "Warning: Missing clipboard utility. Please install wl-clipboard (preferred) or xclip." >&2
     echo "  Value: $text" >&2
     return 1
   fi
@@ -171,12 +172,18 @@ notify_result() {
   notify-send -i "color-picker" "color-tool" "$value" || true
 }
 
+notify_error() {
+  local value="$1"
+  command -v notify-send &>/dev/null || return 0
+  notify-send -u normal -i "dialog-warning" "color-tool" "$value" || true
+}
+
 # ── Color picker ──────────────────────────────────────────────────────────────
 
 # Generate the internal Python helper for KDE Plasma color picking
 generate_picker_script() {
   local target="$1"
-  cat > "$target" <<'EOF'
+  cat >"$target" <<'EOF'
 #!/usr/bin/python3
 #
 # Original work Copyright (C) 2024 SASUPERNOVA
@@ -273,7 +280,7 @@ do_install() {
   local config_file="$config_dir/config.toml"
   mkdir -p "$config_dir"
   if [[ ! -f "$config_file" ]]; then
-    cat > "$config_file" <<'EOF'
+    cat >"$config_file" <<'EOF'
 # color-tool configuration
 # https://github.com/rootiest/color-tool
 
@@ -281,7 +288,6 @@ do_install() {
 # Set any option to true to enable it by default when using the terminal
 output = "hex"  # default output format(s): hex, rgb, hsl, rgba, hsla, hexa, all
 json   = false  # output in JSON format
-alpha  = false  # include alpha channel (8-digit hex)
 swatch = false  # show color swatch in terminal
 name   = false  # fetch color name from thecolorapi.com
 copy   = false  # copy result to clipboard
@@ -292,7 +298,6 @@ notify = false  # show desktop notification
 # Defaults for --desktop mode (launched from the app menu; copy is always enabled by default)
 output = "hex"  # format to copy
 json   = false  # copy JSON format instead of plain text
-alpha  = false  # include alpha channel
 name   = false  # fetch color name (requires network)
 copy   = true   # copy result to clipboard
 notify = true   # show desktop notification with the copied value
@@ -306,7 +311,7 @@ EOF
   local desktop_file="$app_dir/color-tool.desktop"
   local bin_path="$HOME/.local/bin/color-tool"
   mkdir -p "$app_dir"
-  cat > "$desktop_file" <<EOF
+  cat >"$desktop_file" <<EOF
 [Desktop Entry]
 Version=1.1
 Type=Application
@@ -381,7 +386,7 @@ print(json.dumps(formats))
 validate_output_formats() {
   local formats="$1"
   local valid_fmts=("hex" "hexa" "rgb" "rgba" "hsl" "hsla")
-  IFS=',' read -ra ADDR <<< "$formats"
+  IFS=',' read -ra ADDR <<<"$formats"
   for fmt in "${ADDR[@]}"; do
     [[ "$fmt" == "all" ]] && continue
     local is_valid=0
@@ -398,7 +403,10 @@ validate_output_formats() {
 process_color() {
   local input="$1"
   local formats_json
-  formats_json=$(get_all_formats "$input") || { echo "Error: Invalid color: $input" >&2; return 1; }
+  formats_json=$(get_all_formats "$input") || {
+    echo "Error: Invalid color: $input" >&2
+    return 1
+  }
 
   local name=""
   if [[ $name_mode -eq 1 ]]; then
@@ -409,7 +417,7 @@ process_color() {
 
   local selected_fmts=()
   local valid_fmts=("hex" "hexa" "rgb" "rgba" "hsl" "hsla")
-  IFS=',' read -ra ADDR <<< "$output_formats"
+  IFS=',' read -ra ADDR <<<"$output_formats"
   for fmt in "${ADDR[@]}"; do
     if [[ "$fmt" == "all" ]]; then
       selected_fmts=("${valid_fmts[@]}")
@@ -436,7 +444,10 @@ process_color() {
   if [[ $json_mode -eq 1 ]]; then
     output_text="$json_obj"
   else
-    output_text=$(IFS=' ' ; echo "${display_parts[*]}")
+    output_text=$(
+      IFS=' '
+      echo "${display_parts[*]}"
+    )
     [[ -n "$name" ]] && output_text="$output_text ($name)"
   fi
 
@@ -446,14 +457,29 @@ process_color() {
       r=$(echo "$formats_json" | jq -r '._raw.r')
       g=$(echo "$formats_json" | jq -r '._raw.g')
       b=$(echo "$formats_json" | jq -r '._raw.b')
-      if [[ $json_mode -eq 1 ]]; then printf "\033[48;2;${r};${g};${b}m  \033[0m\n"
+      if [[ $json_mode -eq 1 ]]; then
+        printf "\033[48;2;${r};${g};${b}m  \033[0m\n"
       else printf "\033[48;2;${r};${g};${b}m  \033[0m "; fi
     fi
     echo -e "$output_text"
   fi
 
-  [[ $copy_mode -eq 1 ]] && copy_to_clipboard "$output_text" || true
-  [[ $notify_mode -eq 1 ]] && notify_result "$output_text" || true
+  local copy_failed=0
+  if [[ $copy_mode -eq 1 ]]; then
+    if ! copy_to_clipboard "$output_text"; then
+      copy_failed=1
+    fi
+  fi
+
+  if [[ $notify_mode -eq 1 ]]; then
+    if [[ $copy_failed -eq 1 ]]; then
+      notify_error "Missing clipboard utility. Please install wl-clipboard (preferred) or xclip.
+
+Value: $output_text"
+    else
+      notify_result "$output_text"
+    fi
+  fi
 }
 
 # ── Argument parsing ──────────────────────────────────────────────────────────
@@ -465,26 +491,41 @@ do_pick=0
 # First pass: collect CLI overrides
 while [[ $# -gt 0 ]]; do
   case "$1" in
-    --help|-h) show_help; exit 0 ;;
-    --output)  cli_output="$2"; shift ;;
-    --json)    cli_json=1    ;;
-    --no-json) cli_json=0    ;;
-    --alpha)   cli_alpha=1; cli_output="hexa" ;;
-    --no-alpha)cli_alpha=0   ;;
-    --name)    cli_name=1    ;;
-    --no-name) cli_name=0    ;;
-    --swatch)  cli_swatch=1  ;;
-    --no-swatch)cli_swatch=0 ;;
-    --copy)    cli_copy=1    ;;
-    --no-copy) cli_copy=0    ;;
-    --notify)  cli_notify=1  ;;
-    --no-notify)cli_notify=0 ;;
-    --pick)    cli_pick=1    ;;
-    --no-pick) cli_pick=0    ;;
-    --desktop) desktop_mode=1 ;;
-    --install) do_install; exit 0 ;;
-    -*) echo "Unknown option: $1" >&2; exit 1 ;;
-    *) args+=("$1") ;;
+  --help | -h)
+    show_help
+    exit 0
+    ;;
+  --output)
+    cli_output="$2"
+    shift
+    ;;
+  --json) cli_json=1 ;;
+  --no-json) cli_json=0 ;;
+  --alpha)
+    cli_alpha=1
+    cli_output="hexa"
+    ;;
+  --no-alpha) cli_alpha=0 ;;
+  --name) cli_name=1 ;;
+  --no-name) cli_name=0 ;;
+  --swatch) cli_swatch=1 ;;
+  --no-swatch) cli_swatch=0 ;;
+  --copy) cli_copy=1 ;;
+  --no-copy) cli_copy=0 ;;
+  --notify) cli_notify=1 ;;
+  --no-notify) cli_notify=0 ;;
+  --pick) cli_pick=1 ;;
+  --no-pick) cli_pick=0 ;;
+  --desktop) desktop_mode=1 ;;
+  --install)
+    do_install
+    exit 0
+    ;;
+  -*)
+    echo "Unknown option: $1" >&2
+    exit 1
+    ;;
+  *) args+=("$1") ;;
   esac
   shift
 done
@@ -525,7 +566,8 @@ elif [[ ${#args[@]} -eq 0 ]]; then
     picked="$(run_color_picker)" || exit 1
     [[ -n "$picked" ]] && args+=("$picked")
   elif [[ -t 0 ]]; then
-    show_help; exit 0
+    show_help
+    exit 0
   fi
 fi
 

tests/run_tests.sh

@@ -0,0 +1,149 @@
+#!/bin/bash
+set -euo pipefail
+
+# ── Setup ─────────────────────────────────────────────────────────────────────
+# Using a static-ish path since we can't use command substitution in cat
+TEST_DIR="/tmp/color-tool-tests-repro"
+BIN_DIR="$TEST_DIR/bin"
+rm -rf "$TEST_DIR"
+mkdir -p "$BIN_DIR"
+
+# Mock notify-send
+cat <<'MOCK' > "$BIN_DIR/notify-send"
+#!/bin/bash
+echo "NOTIFY: $*" >> "/tmp/color-tool-tests-repro/notify.log"
+MOCK
+
+# Mock wl-copy
+cat <<'MOCK' > "$BIN_DIR/wl-copy"
+#!/bin/bash
+cat > "/tmp/color-tool-tests-repro/clipboard.txt"
+MOCK
+
+# Mock python3
+cat <<'MOCK' > "$BIN_DIR/python3"
+#!/bin/bash
+if [[ "$*" == *wl-colorpicker*.py ]]; then
+  echo "#aabbcc"
+  exit 0
+fi
+exec /usr/bin/python3 "$@"
+MOCK
+
+chmod +x "$BIN_DIR"/*
+
+# Symlink essential tools
+ln -s /usr/bin/bash "$BIN_DIR/bash"
+ln -s /usr/bin/cat "$BIN_DIR/cat"
+ln -s /usr/bin/printf "$BIN_DIR/printf"
+ln -s /usr/bin/echo "$BIN_DIR/echo"
+ln -s /usr/bin/sed "$BIN_DIR/sed"
+ln -s /usr/bin/grep "$BIN_DIR/grep"
+ln -s /usr/bin/awk "$BIN_DIR/awk"
+ln -s /usr/bin/jq "$BIN_DIR/jq"
+ln -s /usr/bin/readlink "$BIN_DIR/readlink"
+ln -s /usr/bin/dirname "$BIN_DIR/dirname"
+ln -s /usr/bin/mkdir "$BIN_DIR/mkdir"
+ln -s /usr/bin/mktemp "$BIN_DIR/mktemp"
+ln -s /usr/bin/chmod "$BIN_DIR/chmod"
+ln -s /usr/bin/rm "$BIN_DIR/rm"
+ln -s /usr/bin/curl "$BIN_DIR/curl"
+
+export PATH="$BIN_DIR"
+export HOME="$TEST_DIR"
+export WAYLAND_DISPLAY=wayland-0
+export XDG_CURRENT_DESKTOP=KDE
+
+# Resolve the absolute path of color-tool
+COLOR_TOOL="$(/usr/bin/readlink -f ./color-tool)"
+
+# ── Test Helpers ──────────────────────────────────────────────────────────────
+total=0
+passed=0
+
+it() {
+  local label="$1"
+  total=$((total + 1))
+  printf "Test: %s... " "$label"
+}
+
+assert_contains() {
+  local haystack="$1"
+  local needle="$2"
+  if [[ "$haystack" == *"$needle"* ]]; then
+    echo "PASS"
+    passed=$((passed + 1))
+  else
+    echo "FAIL"
+    echo "  Expected to find: $needle"
+    echo "  Actual output: $haystack"
+    return 1
+  fi
+}
+
+# ── Tests ─────────────────────────────────────────────────────────────────────
+
+# 1. Basic Conversion
+it "converts hex to rgb"
+output=$("$COLOR_TOOL" "#ffffff" --output rgb --no-copy --no-notify)
+assert_contains "$output" "rgb(255, 255, 255)"
+
+# 2. Multiple Formats
+it "handles multiple formats"
+output=$("$COLOR_TOOL" "#000000" --output hex,rgba --no-copy --no-notify)
+assert_contains "$output" "#000000 rgba(0, 0, 0, 1.0)"
+
+# 3. Clipboard Integration
+it "copies to clipboard (mocked)"
+rm -f "$TEST_DIR/clipboard.txt"
+"$COLOR_TOOL" "#ff0000" --copy --no-notify >/dev/null
+if [[ -f "$TEST_DIR/clipboard.txt" ]]; then
+  assert_contains "$(cat "$TEST_DIR/clipboard.txt")" "#ff0000"
+else
+  echo "FAIL (clipboard.txt not created)"
+fi
+
+# 4. Notification Integration
+it "sends notifications (mocked)"
+rm -f "$TEST_DIR/notify.log"
+"$COLOR_TOOL" "#00ff00" --notify --no-copy >/dev/null
+if [[ -f "$TEST_DIR/notify.log" ]]; then
+  assert_contains "$(cat "$TEST_DIR/notify.log")" "NOTIFY: -i color-picker color-tool #00ff00"
+else
+  echo "FAIL (notify.log not created)"
+fi
+
+# 5. Color Picker (Mocked)
+it "launches color picker and processes result"
+output=$("$COLOR_TOOL" --pick --no-copy --no-notify)
+assert_contains "$output" "#aabbcc"
+
+# 6. Config Loading
+it "loads defaults from config.toml"
+mkdir -p "$HOME/.config/color-tool"
+cat <<'CONF' > "$HOME/.config/color-tool/config.toml"
+[defaults]
+output = "rgba"
+CONF
+output=$("$COLOR_TOOL" "#ffffff" --no-copy --no-notify)
+assert_contains "$output" "rgba(255, 255, 255, 1.0)"
+
+# 7. Error Notification
+it "notifies on missing clipboard utility"
+rm -f "$BIN_DIR/wl-copy"
+rm -f "$TEST_DIR/notify.log"
+"$COLOR_TOOL" "#123456" --copy --notify 2>/dev/null >/dev/null
+if [[ -f "$TEST_DIR/notify.log" ]]; then
+  assert_contains "$(cat "$TEST_DIR/notify.log")" "NOTIFY: -u normal -i dialog-warning color-tool Missing clipboard utility"
+else
+  echo "FAIL (notify.log not created)"
+fi
+
+# ── Cleanup ───────────────────────────────────────────────────────────────────
+echo "---------------------------------------"
+echo "Result: $passed/$total tests passed."
+rm -rf "$TEST_DIR"
+
+if [[ $passed -ne $total ]]; then
+  exit 1
+fi