From 4aeda58a3774e4ca8d74b7873516f3d3108997be Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Thu, 22 Jan 2026 18:37:47 +0000
Subject: [PATCH] test: add unit tests for sync-docs-from-node workflow scripts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add bats-core unit tests for the shell scripts used by the documentation
sync workflow to prevent regressions when updating the docs.

Tests cover:
- version-utils.sh: validate_version function with various SemVer formats
- sanitize-config.sh: config sanitization (RPC URL replacement, dev removal)
- sanitize-docker-compose.sh: docker-compose sanitization (alloy removal)
- sync.sh: file sync logic (add/update/delete, pattern filtering, exclusions)
- aggregate-reports.sh: report aggregation and metric calculation

Also adds a new GitHub workflow (test-workflow-scripts.yml) that runs
these tests on PRs that modify the workflow scripts or actions.

Co-Authored-By: Agustín Díaz <agustin.ramiro.diaz@gmail.com>
---
 .github/tests/aggregate-reports.bats        | 192 +++++++++++++
 .github/tests/sanitize-config.bats          | 106 +++++++
 .github/tests/sanitize-docker-compose.bats  | 117 ++++++++
 .github/tests/sync.bats                     | 300 ++++++++++++++++++++
 .github/tests/version-utils.bats            | 109 +++++++
 .github/workflows/test-workflow-scripts.yml |  58 ++++
 6 files changed, 882 insertions(+)
 create mode 100644 .github/tests/aggregate-reports.bats
 create mode 100644 .github/tests/sanitize-config.bats
 create mode 100644 .github/tests/sanitize-docker-compose.bats
 create mode 100644 .github/tests/sync.bats
 create mode 100644 .github/tests/version-utils.bats
 create mode 100644 .github/workflows/test-workflow-scripts.yml

diff --git a/.github/tests/aggregate-reports.bats b/.github/tests/aggregate-reports.bats
new file mode 100644
index 00000000..6c981cb8
--- /dev/null
+++ b/.github/tests/aggregate-reports.bats
@@ -0,0 +1,192 @@
+#!/usr/bin/env bats
+
+# Unit tests for aggregate-reports.sh
+
+setup() {
+    export TEST_DIR=$(mktemp -d)
+    export SCRIPT_PATH="$BATS_TEST_DIRNAME/../scripts/aggregate-reports.sh"
+    export GITHUB_OUTPUT=$(mktemp)
+    
+    # Create sync-reports directory
+    mkdir -p "$TEST_DIR/sync-reports"
+    
+    # Change to test directory
+    cd "$TEST_DIR"
+}
+
+teardown() {
+    rm -rf "$TEST_DIR"
+    rm -f "$GITHUB_OUTPUT"
+}
+
+# ============================================
+# Tests for aggregate_sync_reports()
+# ============================================
+
+@test "aggregate-reports: calculates totals from single report" {
+    cat > "$TEST_DIR/sync-reports/sync_report_changelog.md" <<EOF
+## Changelog
+
+### Summary
+- **Added**: 3 files
+- **Updated**: 2 files
+- **Deleted**: 1 files
+- **Total changes**: 6
+EOF
+    
+    run bash "$SCRIPT_PATH"
+    [ "$status" -eq 0 ]
+    
+    # Check totals
+    run grep "total_changes=6" "$GITHUB_OUTPUT"
+    [ "$status" -eq 0 ]
+    
+    run grep "total_added=3" "$GITHUB_OUTPUT"
+    [ "$status" -eq 0 ]
+    
+    run grep "total_updated=2" "$GITHUB_OUTPUT"
+    [ "$status" -eq 0 ]
+    
+    run grep "total_deleted=1" "$GITHUB_OUTPUT"
+    [ "$status" -eq 0 ]
+}
+
+@test "aggregate-reports: aggregates multiple reports" {
+    cat > "$TEST_DIR/sync-reports/sync_report_changelog.md" <<EOF
+## Changelog
+
+### Summary
+- **Added**: 2 files
+- **Updated**: 1 files
+- **Deleted**: 0 files
+- **Total changes**: 3
+EOF
+
+    cat > "$TEST_DIR/sync-reports/sync_report_api_gen.md" <<EOF
+## API Gen
+
+### Summary
+- **Added**: 5 files
+- **Updated**: 3 files
+- **Deleted**: 2 files
+- **Total changes**: 10
+EOF
+    
+    run bash "$SCRIPT_PATH"
+    [ "$status" -eq 0 ]
+    
+    # Check aggregated totals (2+5=7 added, 1+3=4 updated, 0+2=2 deleted, 3+10=13 total)
+    run grep "total_changes=13" "$GITHUB_OUTPUT"
+    [ "$status" -eq 0 ]
+    
+    run grep "total_added=7" "$GITHUB_OUTPUT"
+    [ "$status" -eq 0 ]
+    
+    run grep "total_updated=4" "$GITHUB_OUTPUT"
+    [ "$status" -eq 0 ]
+    
+    run grep "total_deleted=2" "$GITHUB_OUTPUT"
+    [ "$status" -eq 0 ]
+}
+
+@test "aggregate-reports: handles report with no changes" {
+    cat > "$TEST_DIR/sync-reports/sync_report_config.md" <<EOF
+## Config
+
+### Summary
+- **Added**: 0 files
+- **Updated**: 0 files
+- **Deleted**: 0 files
+- **Total changes**: 0
+EOF
+    
+    run bash "$SCRIPT_PATH"
+    [ "$status" -eq 0 ]
+    
+    run grep "total_changes=0" "$GITHUB_OUTPUT"
+    [ "$status" -eq 0 ]
+}
+
+@test "aggregate-reports: handles missing sync-reports directory" {
+    rm -rf "$TEST_DIR/sync-reports"
+    
+    run bash "$SCRIPT_PATH"
+    [ "$status" -eq 0 ]
+    
+    # Should output zeros
+    run grep "total_changes=0" "$GITHUB_OUTPUT"
+    [ "$status" -eq 0 ]
+}
+
+@test "aggregate-reports: handles empty sync-reports directory" {
+    # Directory exists but is empty
+    run bash "$SCRIPT_PATH"
+    [ "$status" -eq 0 ]
+    
+    run grep "total_changes=0" "$GITHUB_OUTPUT"
+    [ "$status" -eq 0 ]
+}
+
+@test "aggregate-reports: handles report with 'No updates found' message" {
+    cat > "$TEST_DIR/sync-reports/sync_report_config.md" <<EOF
+## Config
+
+No config updates found
+EOF
+    
+    run bash "$SCRIPT_PATH"
+    [ "$status" -eq 0 ]
+    
+    # Should not count this as a change
+    run grep "total_changes=0" "$GITHUB_OUTPUT"
+    [ "$status" -eq 0 ]
+}
+
+@test "aggregate-reports: outputs all_reports multiline content" {
+    cat > "$TEST_DIR/sync-reports/sync_report_test.md" <<EOF
+## Test Report
+
+### Summary
+- **Added**: 1 files
+- **Updated**: 0 files
+- **Deleted**: 0 files
+- **Total changes**: 1
+
+### Added Files
+- test_file.mdx
+EOF
+    
+    run bash "$SCRIPT_PATH"
+    [ "$status" -eq 0 ]
+    
+    # Check that all_reports is in the output
+    run grep "all_reports<<EOF" "$GITHUB_OUTPUT"
+    [ "$status" -eq 0 ]
+}
+
+@test "aggregate-reports: handles all six sync types" {
+    for sync_type in changelog config docker_compose api_gen api_debug api_ops; do
+        cat > "$TEST_DIR/sync-reports/sync_report_${sync_type}.md" <<EOF
+## ${sync_type}
+
+### Summary
+- **Added**: 1 files
+- **Updated**: 1 files
+- **Deleted**: 0 files
+- **Total changes**: 2
+EOF
+    done
+    
+    run bash "$SCRIPT_PATH"
+    [ "$status" -eq 0 ]
+    
+    # Total should be 6 types * 2 changes each = 12
+    run grep "total_changes=12" "$GITHUB_OUTPUT"
+    [ "$status" -eq 0 ]
+    
+    run grep "total_added=6" "$GITHUB_OUTPUT"
+    [ "$status" -eq 0 ]
+    
+    run grep "total_updated=6" "$GITHUB_OUTPUT"
+    [ "$status" -eq 0 ]
+}
diff --git a/.github/tests/sanitize-config.bats b/.github/tests/sanitize-config.bats
new file mode 100644
index 00000000..25effa21
--- /dev/null
+++ b/.github/tests/sanitize-config.bats
@@ -0,0 +1,106 @@
+#!/usr/bin/env bats
+
+# Unit tests for sanitize-config.sh
+
+setup() {
+    export TEST_DIR=$(mktemp -d)
+    export SCRIPT_PATH="$BATS_TEST_DIRNAME/../scripts/sanitize-config.sh"
+}
+
+teardown() {
+    rm -rf "$TEST_DIR"
+}
+
+# ============================================
+# Tests for sanitize-config.sh
+# ============================================
+
+@test "sanitize-config: replaces genlayerchainrpcurl with TODO placeholder" {
+    # Create test config
+    cat > "$TEST_DIR/config.yaml" <<EOF
+rollup:
+  genlayerchainrpcurl: "https://secret-rpc.example.com"
+  genlayerchainwebsocketurl: "wss://secret-ws.example.com"
+  other: "value"
+EOF
+    
+    run bash "$SCRIPT_PATH" "$TEST_DIR/config.yaml"
+    [ "$status" -eq 0 ]
+    
+    # Check that RPC URL was replaced
+    run grep "TODO: Set your GenLayer Chain ZKSync HTTP RPC URL here" "$TEST_DIR/config.yaml"
+    [ "$status" -eq 0 ]
+}
+
+@test "sanitize-config: replaces genlayerchainwebsocketurl with TODO placeholder" {
+    cat > "$TEST_DIR/config.yaml" <<EOF
+rollup:
+  genlayerchainrpcurl: "https://secret-rpc.example.com"
+  genlayerchainwebsocketurl: "wss://secret-ws.example.com"
+EOF
+    
+    run bash "$SCRIPT_PATH" "$TEST_DIR/config.yaml"
+    [ "$status" -eq 0 ]
+    
+    # Check that WebSocket URL was replaced
+    run grep "TODO: Set your GenLayer Chain ZKSync WebSocket RPC URL here" "$TEST_DIR/config.yaml"
+    [ "$status" -eq 0 ]
+}
+
+@test "sanitize-config: removes node.dev section" {
+    cat > "$TEST_DIR/config.yaml" <<EOF
+rollup:
+  genlayerchainrpcurl: "https://rpc.example.com"
+  genlayerchainwebsocketurl: "wss://ws.example.com"
+node:
+  production: true
+  dev:
+    debug: true
+    verbose: true
+EOF
+    
+    run bash "$SCRIPT_PATH" "$TEST_DIR/config.yaml"
+    [ "$status" -eq 0 ]
+    
+    # Check that dev section was removed
+    run grep "dev:" "$TEST_DIR/config.yaml"
+    [ "$status" -ne 0 ]
+    
+    # Check that production section still exists
+    run grep "production: true" "$TEST_DIR/config.yaml"
+    [ "$status" -eq 0 ]
+}
+
+@test "sanitize-config: preserves other config values" {
+    cat > "$TEST_DIR/config.yaml" <<EOF
+rollup:
+  genlayerchainrpcurl: "https://rpc.example.com"
+  genlayerchainwebsocketurl: "wss://ws.example.com"
+  chainid: 12345
+server:
+  port: 8080
+  host: "0.0.0.0"
+EOF
+    
+    run bash "$SCRIPT_PATH" "$TEST_DIR/config.yaml"
+    [ "$status" -eq 0 ]
+    
+    # Check that other values are preserved
+    run grep "chainid: 12345" "$TEST_DIR/config.yaml"
+    [ "$status" -eq 0 ]
+    
+    run grep "port: 8080" "$TEST_DIR/config.yaml"
+    [ "$status" -eq 0 ]
+}
+
+@test "sanitize-config: fails with missing argument" {
+    run bash "$SCRIPT_PATH"
+    [ "$status" -eq 1 ]
+    [[ "$output" == *"Usage:"* ]]
+}
+
+@test "sanitize-config: fails with non-existent file" {
+    run bash "$SCRIPT_PATH" "$TEST_DIR/nonexistent.yaml"
+    [ "$status" -eq 1 ]
+    [[ "$output" == *"File not found"* ]]
+}
diff --git a/.github/tests/sanitize-docker-compose.bats b/.github/tests/sanitize-docker-compose.bats
new file mode 100644
index 00000000..c9493852
--- /dev/null
+++ b/.github/tests/sanitize-docker-compose.bats
@@ -0,0 +1,117 @@
+#!/usr/bin/env bats
+
+# Unit tests for sanitize-docker-compose.sh
+
+setup() {
+    export TEST_DIR=$(mktemp -d)
+    export SCRIPT_PATH="$BATS_TEST_DIRNAME/../scripts/sanitize-docker-compose.sh"
+}
+
+teardown() {
+    rm -rf "$TEST_DIR"
+}
+
+# ============================================
+# Tests for sanitize-docker-compose.sh
+# ============================================
+
+@test "sanitize-docker-compose: removes alloy service" {
+    cat > "$TEST_DIR/docker-compose.yaml" <<EOF
+services:
+  genlayer-node:
+    image: genlayer/node:latest
+    ports:
+      - "8080:8080"
+  alloy:
+    image: grafana/alloy:latest
+    ports:
+      - "9090:9090"
+volumes:
+  data:
+EOF
+    
+    run bash "$SCRIPT_PATH" "$TEST_DIR/docker-compose.yaml"
+    [ "$status" -eq 0 ]
+    
+    # Check that alloy service was removed
+    run grep "alloy:" "$TEST_DIR/docker-compose.yaml"
+    [ "$status" -ne 0 ]
+    
+    # Check that genlayer-node service still exists
+    run grep "genlayer-node:" "$TEST_DIR/docker-compose.yaml"
+    [ "$status" -eq 0 ]
+}
+
+@test "sanitize-docker-compose: removes volumes section" {
+    cat > "$TEST_DIR/docker-compose.yaml" <<EOF
+services:
+  genlayer-node:
+    image: genlayer/node:latest
+volumes:
+  data:
+  logs:
+EOF
+    
+    run bash "$SCRIPT_PATH" "$TEST_DIR/docker-compose.yaml"
+    [ "$status" -eq 0 ]
+    
+    # Check that volumes section was removed
+    run grep "^volumes:" "$TEST_DIR/docker-compose.yaml"
+    [ "$status" -ne 0 ]
+}
+
+@test "sanitize-docker-compose: preserves other services" {
+    cat > "$TEST_DIR/docker-compose.yaml" <<EOF
+services:
+  genlayer-node:
+    image: genlayer/node:latest
+    environment:
+      - NODE_ENV=production
+  postgres:
+    image: postgres:15
+    ports:
+      - "5432:5432"
+  alloy:
+    image: grafana/alloy:latest
+volumes:
+  pgdata:
+EOF
+    
+    run bash "$SCRIPT_PATH" "$TEST_DIR/docker-compose.yaml"
+    [ "$status" -eq 0 ]
+    
+    # Check that postgres service still exists
+    run grep "postgres:" "$TEST_DIR/docker-compose.yaml"
+    [ "$status" -eq 0 ]
+    
+    # Check that genlayer-node service still exists
+    run grep "genlayer-node:" "$TEST_DIR/docker-compose.yaml"
+    [ "$status" -eq 0 ]
+}
+
+@test "sanitize-docker-compose: handles file without alloy service" {
+    cat > "$TEST_DIR/docker-compose.yaml" <<EOF
+services:
+  genlayer-node:
+    image: genlayer/node:latest
+EOF
+    
+    run bash "$SCRIPT_PATH" "$TEST_DIR/docker-compose.yaml"
+    [ "$status" -eq 0 ]
+    
+    # Check that genlayer-node service still exists
+    run grep "genlayer-node:" "$TEST_DIR/docker-compose.yaml"
+    [ "$status" -eq 0 ]
+}
+
+@test "sanitize-docker-compose: fails with missing argument" {
+    run bash "$SCRIPT_PATH"
+    [ "$status" -eq 1 ]
+    [[ "$output" == *"Usage:"* ]]
+}
+
+@test "sanitize-docker-compose: fails with non-existent file" {
+    run bash "$SCRIPT_PATH" "$TEST_DIR/nonexistent.yaml"
+    [ "$status" -eq 1 ]
+    [[ "$output" == *"File not found"* ]]
+}
diff --git a/.github/tests/sync.bats b/.github/tests/sync.bats
new file mode 100644
index 00000000..a9adb2fa
--- /dev/null
+++ b/.github/tests/sync.bats
@@ -0,0 +1,300 @@
+#!/usr/bin/env bats
+
+# Unit tests for sync.sh (the core file synchronization script)
+
+setup() {
+    export TEST_DIR=$(mktemp -d)
+    export SCRIPT_PATH="$BATS_TEST_DIRNAME/../actions/sync-files/sync.sh"
+    export GITHUB_OUTPUT=$(mktemp)
+    
+    # Create source and target directories
+    mkdir -p "$TEST_DIR/source"
+    mkdir -p "$TEST_DIR/target"
+    mkdir -p "$TEST_DIR/artifacts"
+}
+
+teardown() {
+    rm -rf "$TEST_DIR"
+    rm -f "$GITHUB_OUTPUT"
+}
+
+# ============================================
+# Tests for single file sync
+# ============================================
+
+@test "sync: adds new single file" {
+    echo "content" > "$TEST_DIR/source/file.yaml"
+    
+    run bash "$SCRIPT_PATH" "test" "Test" "$TEST_DIR/source/file.yaml" "$TEST_DIR/target/file.yaml" ".*" ""
+    [ "$status" -eq 0 ]
+    
+    # Check file was copied
+    [ -f "$TEST_DIR/target/file.yaml" ]
+    
+    # Check metrics
+    run grep "added=1" "$GITHUB_OUTPUT"
+    [ "$status" -eq 0 ]
+}
+
+@test "sync: updates existing single file when content differs" {
+    echo "old content" > "$TEST_DIR/target/file.yaml"
+    echo "new content" > "$TEST_DIR/source/file.yaml"
+    
+    run bash "$SCRIPT_PATH" "test" "Test" "$TEST_DIR/source/file.yaml" "$TEST_DIR/target/file.yaml" ".*" ""
+    [ "$status" -eq 0 ]
+    
+    # Check file was updated
+    run cat "$TEST_DIR/target/file.yaml"
+    [ "$output" = "new content" ]
+    
+    # Check metrics
+    run grep "updated=1" "$GITHUB_OUTPUT"
+    [ "$status" -eq 0 ]
+}
+
+@test "sync: does not update file when content is same" {
+    echo "same content" > "$TEST_DIR/source/file.yaml"
+    echo "same content" > "$TEST_DIR/target/file.yaml"
+    
+    run bash "$SCRIPT_PATH" "test" "Test" "$TEST_DIR/source/file.yaml" "$TEST_DIR/target/file.yaml" ".*" ""
+    [ "$status" -eq 0 ]
+    
+    # Check metrics show no changes
+    run grep "updated=0" "$GITHUB_OUTPUT"
+    [ "$status" -eq 0 ]
+    run grep "added=0" "$GITHUB_OUTPUT"
+    [ "$status" -eq 0 ]
+}
+
+# ============================================
+# Tests for directory sync
+# ============================================
+
+@test "sync: adds new files from directory" {
+    echo "content1" > "$TEST_DIR/source/file1.mdx"
+    echo "content2" > "$TEST_DIR/source/file2.mdx"
+    
+    run bash "$SCRIPT_PATH" "test" "Test" "$TEST_DIR/source" "$TEST_DIR/target" ".*" ""
+    [ "$status" -eq 0 ]
+    
+    # Check files were copied
+    [ -f "$TEST_DIR/target/file1.mdx" ]
+    [ -f "$TEST_DIR/target/file2.mdx" ]
+    
+    # Check metrics
+    run grep "added=2" "$GITHUB_OUTPUT"
+    [ "$status" -eq 0 ]
+}
+
+@test "sync: updates changed files in directory" {
+    echo "old content" > "$TEST_DIR/target/file1.mdx"
+    echo "new content" > "$TEST_DIR/source/file1.mdx"
+    
+    run bash "$SCRIPT_PATH" "test" "Test" "$TEST_DIR/source" "$TEST_DIR/target" ".*" ""
+    [ "$status" -eq 0 ]
+    
+    # Check file was updated
+    run cat "$TEST_DIR/target/file1.mdx"
+    [ "$output" = "new content" ]
+    
+    # Check metrics
+    run grep "updated=1" "$GITHUB_OUTPUT"
+    [ "$status" -eq 0 ]
+}
+
+@test "sync: deletes orphaned files from target" {
+    echo "content" > "$TEST_DIR/source/file1.mdx"
+    echo "orphan" > "$TEST_DIR/target/orphan.mdx"
+    
+    run bash "$SCRIPT_PATH" "test" "Test" "$TEST_DIR/source" "$TEST_DIR/target" ".*" ""
+    [ "$status" -eq 0 ]
+    
+    # Check orphan was deleted
+    [ ! -f "$TEST_DIR/target/orphan.mdx" ]
+    
+    # Check metrics
+    run grep "deleted=1" "$GITHUB_OUTPUT"
+    [ "$status" -eq 0 ]
+}
+
+@test "sync: preserves _meta.json file" {
+    echo "content" > "$TEST_DIR/source/file1.mdx"
+    echo '{"file1": "File 1"}' > "$TEST_DIR/target/_meta.json"
+    
+    run bash "$SCRIPT_PATH" "test" "Test" "$TEST_DIR/source" "$TEST_DIR/target" ".*" ""
+    [ "$status" -eq 0 ]
+    
+    # Check _meta.json was preserved
+    [ -f "$TEST_DIR/target/_meta.json" ]
+}
+
+# ============================================
+# Tests for pattern filtering
+# ============================================
+
+@test "sync: filters files by pattern - includes matching" {
+    echo "gen content" > "$TEST_DIR/source/gen_method.mdx"
+    echo "other content" > "$TEST_DIR/source/other_method.mdx"
+    
+    run bash "$SCRIPT_PATH" "test" "Test" "$TEST_DIR/source" "$TEST_DIR/target" "gen_.*" ""
+    [ "$status" -eq 0 ]
+    
+    # Check only matching file was copied
+    [ -f "$TEST_DIR/target/gen_method.mdx" ]
+    [ ! -f "$TEST_DIR/target/other_method.mdx" ]
+}
+
+@test "sync: filters files by pattern - excludes non-matching" {
+    echo "content1" > "$TEST_DIR/source/gen_call.mdx"
+    echo "content2" > "$TEST_DIR/source/gen_send.mdx"
+    echo "content3" > "$TEST_DIR/source/eth_call.mdx"
+    
+    run bash "$SCRIPT_PATH" "test" "Test" "$TEST_DIR/source" "$TEST_DIR/target" "gen_.*" ""
+    [ "$status" -eq 0 ]
+    
+    # Check only gen_ files were copied
+    [ -f "$TEST_DIR/target/gen_call.mdx" ]
+    [ -f "$TEST_DIR/target/gen_send.mdx" ]
+    [ ! -f "$TEST_DIR/target/eth_call.mdx" ]
+}
+
+@test "sync: handles .* pattern (match all)" {
+    echo "content1" > "$TEST_DIR/source/file1.mdx"
+    echo "content2" > "$TEST_DIR/source/file2.mdx"
+    
+    run bash "$SCRIPT_PATH" "test" "Test" "$TEST_DIR/source" "$TEST_DIR/target" ".*" ""
+    [ "$status" -eq 0 ]
+    
+    # Check all files were copied
+    [ -f "$TEST_DIR/target/file1.mdx" ]
+    [ -f "$TEST_DIR/target/file2.mdx" ]
+}
+
+# ============================================
+# Tests for file exclusions
+# ============================================
+
+@test "sync: excludes README files" {
+    echo "content" > "$TEST_DIR/source/file1.mdx"
+    echo "readme" > "$TEST_DIR/source/README.mdx"
+    
+    run bash "$SCRIPT_PATH" "test" "Test" "$TEST_DIR/source" "$TEST_DIR/target" ".*" "README"
+    [ "$status" -eq 0 ]
+    
+    # Check README was excluded
+    [ -f "$TEST_DIR/target/file1.mdx" ]
+    [ ! -f "$TEST_DIR/target/README.mdx" ]
+}
+
+@test "sync: excludes multiple files" {
+    echo "content" > "$TEST_DIR/source/file1.mdx"
+    echo "readme" > "$TEST_DIR/source/README.mdx"
+    echo "changelog" > "$TEST_DIR/source/CHANGELOG.mdx"
+    
+    run bash "$SCRIPT_PATH" "test" "Test" "$TEST_DIR/source" "$TEST_DIR/target" ".*" "README,CHANGELOG"
+    [ "$status" -eq 0 ]
+    
+    # Check excluded files were not copied
+    [ -f "$TEST_DIR/target/file1.mdx" ]
+    [ ! -f "$TEST_DIR/target/README.mdx" ]
+    [ ! -f "$TEST_DIR/target/CHANGELOG.mdx" ]
+}
+
+@test "sync: default exclusions work" {
+    echo "content" > "$TEST_DIR/source/file1.mdx"
+    echo "readme" > "$TEST_DIR/source/README.mdx"
+    echo "changelog" > "$TEST_DIR/source/CHANGELOG.mdx"
+    echo "gitignore" > "$TEST_DIR/source/.gitignore.mdx"
+    
+    # Use default exclusions
+    run bash "$SCRIPT_PATH" "test" "Test" "$TEST_DIR/source" "$TEST_DIR/target" ".*" "README,CHANGELOG,.gitignore,.gitkeep"
+    [ "$status" -eq 0 ]
+    
+    # Check only file1 was copied
+    [ -f "$TEST_DIR/target/file1.mdx" ]
+    [ ! -f "$TEST_DIR/target/README.mdx" ]
+    [ ! -f "$TEST_DIR/target/CHANGELOG.mdx" ]
+}
+
+# ============================================
+# Tests for .md to .mdx conversion
+# ============================================
+
+@test "sync: converts .md files to .mdx" {
+    echo "markdown content" > "$TEST_DIR/source/file.md"
+    
+    run bash "$SCRIPT_PATH" "test" "Test" "$TEST_DIR/source" "$TEST_DIR/target" ".*" ""
+    [ "$status" -eq 0 ]
+    
+    # Check file was converted to .mdx
+    [ -f "$TEST_DIR/target/file.mdx" ]
+    [ ! -f "$TEST_DIR/target/file.md" ]
+}
+
+@test "sync: handles mixed .md and .mdx files" {
+    echo "md content" > "$TEST_DIR/source/file1.md"
+    echo "mdx content" > "$TEST_DIR/source/file2.mdx"
+    
+    run bash "$SCRIPT_PATH" "test" "Test" "$TEST_DIR/source" "$TEST_DIR/target" ".*" ""
+    [ "$status" -eq 0 ]
+    
+    # Check both files exist as .mdx
+    [ -f "$TEST_DIR/target/file1.mdx" ]
+    [ -f "$TEST_DIR/target/file2.mdx" ]
+}
+
+# ============================================
+# Tests for report generation
+# ============================================
+
+@test "sync: generates sync report" {
+    echo "content" > "$TEST_DIR/source/file1.mdx"
+    
+    cd "$TEST_DIR"
+    run bash "$SCRIPT_PATH" "test_type" "Test Title" "$TEST_DIR/source" "$TEST_DIR/target" ".*" ""
+    [ "$status" -eq 0 ]
+    
+    # Check report was created
+    [ -f "artifacts/sync_report_test_type.md" ]
+    
+    # Check report contains expected content
+    run grep "Test Title" "artifacts/sync_report_test_type.md"
+    [ "$status" -eq 0 ]
+    
+    run grep "Added" "artifacts/sync_report_test_type.md"
+    [ "$status" -eq 0 ]
+}
+
+# ============================================
+# Tests for error handling
+# ============================================
+
+@test "sync: fails when source does not exist" {
+    run bash "$SCRIPT_PATH" "test" "Test" "$TEST_DIR/nonexistent" "$TEST_DIR/target" ".*" ""
+    [ "$status" -eq 1 ]
+    [[ "$output" == *"Source not found"* ]]
+}
+
+@test "sync: handles empty source directory" {
+    # Source directory exists but is empty
+    run bash "$SCRIPT_PATH" "test" "Test" "$TEST_DIR/source" "$TEST_DIR/target" ".*" ""
+    [ "$status" -eq 0 ]
+    
+    # Check metrics show no changes
+    run grep "total=0" "$GITHUB_OUTPUT"
+    [ "$status" -eq 0 ]
+}
+
+@test "sync: does not delete when source has no matching files" {
+    # Create target file
+    echo "existing" > "$TEST_DIR/target/existing.mdx"
+    
+    # Source has no .md or .mdx files
+    echo "not markdown" > "$TEST_DIR/source/file.txt"
+    
+    run bash "$SCRIPT_PATH" "test" "Test" "$TEST_DIR/source" "$TEST_DIR/target" ".*" ""
+    [ "$status" -eq 0 ]
+    
+    # Check existing file was NOT deleted (safety feature)
+    [ -f "$TEST_DIR/target/existing.mdx" ]
+}
diff --git a/.github/tests/version-utils.bats b/.github/tests/version-utils.bats
new file mode 100644
index 00000000..d8786e96
--- /dev/null
+++ b/.github/tests/version-utils.bats
@@ -0,0 +1,109 @@
+#!/usr/bin/env bats
+
+# Unit tests for version-utils.sh
+
+setup() {
+    # Load the script functions
+    source "$BATS_TEST_DIRNAME/../scripts/version-utils.sh" 2>/dev/null || true
+    
+    # Create temp directory for test outputs
+    export GITHUB_OUTPUT=$(mktemp)
+}
+
+teardown() {
+    rm -f "$GITHUB_OUTPUT"
+}
+
+# ============================================
+# Tests for validate_version()
+# ============================================
+
+@test "validate_version: accepts 'latest'" {
+    run validate_version "latest"
+    [ "$status" -eq 0 ]
+}
+
+@test "validate_version: accepts simple semver v1.0.0" {
+    run validate_version "v1.0.0"
+    [ "$status" -eq 0 ]
+}
+
+@test "validate_version: accepts v0.4.3" {
+    run validate_version "v0.4.3"
+    [ "$status" -eq 0 ]
+}
+
+@test "validate_version: accepts v10.20.30" {
+    run validate_version "v10.20.30"
+    [ "$status" -eq 0 ]
+}
+
+@test "validate_version: accepts prerelease v1.2.3-rc.1" {
+    run validate_version "v1.2.3-rc.1"
+    [ "$status" -eq 0 ]
+}
+
+@test "validate_version: accepts prerelease v1.2.3-alpha.2" {
+    run validate_version "v1.2.3-alpha.2"
+    [ "$status" -eq 0 ]
+}
+
+@test "validate_version: accepts prerelease v1.2.3-beta.1" {
+    run validate_version "v1.2.3-beta.1"
+    [ "$status" -eq 0 ]
+}
+
+@test "validate_version: accepts build metadata v1.2.3+build.7" {
+    run validate_version "v1.2.3+build.7"
+    [ "$status" -eq 0 ]
+}
+
+@test "validate_version: accepts full semver v1.2.3-beta.1+exp.sha.5114f85" {
+    run validate_version "v1.2.3-beta.1+exp.sha.5114f85"
+    [ "$status" -eq 0 ]
+}
+
+@test "validate_version: accepts testnet version v0.4.0-testnet123" {
+    run validate_version "v0.4.0-testnet123"
+    [ "$status" -eq 0 ]
+}
+
+@test "validate_version: rejects version without v prefix" {
+    run validate_version "1.0.0"
+    [ "$status" -eq 1 ]
+}
+
+@test "validate_version: rejects invalid format 'main'" {
+    run validate_version "main"
+    [ "$status" -eq 1 ]
+}
+
+@test "validate_version: rejects invalid format 'release-1.0'" {
+    run validate_version "release-1.0"
+    [ "$status" -eq 1 ]
+}
+
+@test "validate_version: rejects empty string" {
+    run validate_version ""
+    [ "$status" -eq 1 ]
+}
+
+@test "validate_version: rejects version with only two parts v1.0" {
+    run validate_version "v1.0"
+    [ "$status" -eq 1 ]
+}
+
+@test "validate_version: rejects version with four parts v1.0.0.0" {
+    run validate_version "v1.0.0.0"
+    [ "$status" -eq 1 ]
+}
+
+@test "validate_version: rejects version with spaces" {
+    run validate_version "v1.0.0 "
+    [ "$status" -eq 1 ]
+}
+
+@test "validate_version: rejects version with leading space" {
+    run validate_version " v1.0.0"
+    [ "$status" -eq 1 ]
+}
diff --git a/.github/workflows/test-workflow-scripts.yml b/.github/workflows/test-workflow-scripts.yml
new file mode 100644
index 00000000..d0e6c091
--- /dev/null
+++ b/.github/workflows/test-workflow-scripts.yml
@@ -0,0 +1,58 @@
+name: Test Workflow Scripts
+
+on:
+  pull_request:
+    paths:
+      - '.github/scripts/**'
+      - '.github/actions/**'
+      - '.github/tests/**'
+      - '.github/workflows/sync-docs-from-node.yml'
+      - '.github/workflows/test-workflow-scripts.yml'
+  push:
+    branches:
+      - main
+    paths:
+      - '.github/scripts/**'
+      - '.github/actions/**'
+      - '.github/tests/**'
+      - '.github/workflows/sync-docs-from-node.yml'
+      - '.github/workflows/test-workflow-scripts.yml'
+  workflow_dispatch:
+
+jobs:
+  test-scripts:
+    name: Run Shell Script Tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install bats-core
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y bats
+
+      - name: Install yq (required for sanitization scripts)
+        run: |
+          sudo wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64
+          sudo chmod +x /usr/local/bin/yq
+
+      - name: Run version-utils tests
+        run: bats .github/tests/version-utils.bats
+
+      - name: Run sanitize-config tests
+        run: bats .github/tests/sanitize-config.bats
+
+      - name: Run sanitize-docker-compose tests
+        run: bats .github/tests/sanitize-docker-compose.bats
+
+      - name: Run sync tests
+        run: bats .github/tests/sync.bats
+
+      - name: Run aggregate-reports tests
+        run: bats .github/tests/aggregate-reports.bats
+
+      - name: Run all tests (summary)
+        run: |
+          echo "Running all bats tests..."
+          bats .github/tests/*.bats --tap