Testing

This page covers the project’s testing approach, how to run tests locally, and how to add new test cases.

Test Suite Overview

The project uses shell-based tests to validate the entrypoint script behavior. Tests use a mock binary approach to avoid requiring Docker or actual Telegram credentials. Test location: tests/run.sh What tests validate:

Required environment variable validation
Default argument construction
Custom configuration handling
--local flag behavior
Extra arguments passthrough
Command execution passthrough

Running Tests Locally

Navigate to project root

Ensure you’re in the repository root directory:

cd /path/to/telegram-bot-api-docker

Run the test suite

Execute the test script:

bash tests/run.sh

Review results

Successful output:

[TEST] missing API ID
[PASS] missing API ID
[TEST] missing API HASH
[PASS] missing API HASH
[TEST] builds default args
[PASS] builds default args
[TEST] custom args and --local
[PASS] custom args and --local
[TEST] --local with TELEGRAM_LOCAL=1
[PASS] --local with TELEGRAM_LOCAL=1
[TEST] extra args passthrough
[PASS] extra args passthrough
[TEST] exec passthrough
[PASS] exec passthrough
All tests passed.

Tests run entirely in userspace without Docker. They use a mock telegram-bot-api binary that echoes arguments instead of starting the actual server.

Test Coverage

The test suite validates these scenarios:

1. Missing API ID

Test: test_missing_api_id Validates: Script exits with error when TELEGRAM_API_ID is not set.

test_missing_api_id() {
  local dir
  dir=$(setup_sandbox)
  if output=$(cd "$dir" && env -u TELEGRAM_API_ID -u TELEGRAM_API_HASH ./entrypoint.sh 2>&1); then
    echo "Expected failure when TELEGRAM_API_ID is missing"
    return 1
  else
    echo "$output" | grep -q "Error: TELEGRAM_API_ID is not set"
  fi
}

2. Missing API Hash

Test: test_missing_api_hash Validates: Script exits with error when TELEGRAM_API_HASH is not set.

3. Default Arguments

Test: test_builds_expected_args_defaults Validates: Entrypoint constructs correct default arguments:

--http-port 8081
--http-stat-port 8082
--dir /data
--temp-dir /tmp
--log /data/logs/telegram-bot-api.log

4. Custom Configuration

Test: test_custom_args_and_local Validates: Custom environment variables override defaults:

TELEGRAM_HTTP_PORT=9000
TELEGRAM_HTTP_STAT_PORT=9100
TELEGRAM_DIR=/xdata
TELEGRAM_TEMP_DIR=/xtmp
TELEGRAM_LOG_FILE=/xlogs/app.log
TELEGRAM_LOCAL=true

5. Local Mode Flag

Test: test_local_with_numeric_flag Validates: Both TELEGRAM_LOCAL=true and TELEGRAM_LOCAL=1 enable the --local flag.

6. Extra Arguments

Test: test_extra_args_passthrough Validates: TELEGRAM_EXTRA_ARGS are passed verbatim to the binary:

TELEGRAM_EXTRA_ARGS="--max-webhook-connections 50 --log-verbosity-level 3"

7. Command Passthrough

Test: test_exec_passthrough_when_args_present Validates: Entrypoint executes alternative commands when positional arguments are provided:

./entrypoint.sh echo hello

Test Structure

The test framework (tests/run.sh) provides these helper functions:

`run_test(name, function)`

Executes a test function and tracks pass/fail status:

run_test() {
  local name=$1
  shift
  echo "[TEST] ${name}"
  if "$@"; then
    echo "[PASS] ${name}"
  else
    echo "[FAIL] ${name}"
    failures=$((failures+1))
  fi
}

`setup_sandbox()`

Creates an isolated temporary directory with:

A copy of entrypoint.sh
A mock telegram-bot-api binary

setup_sandbox() {
  local dir
  dir=$(mktemp_dir)
  cleanup_dirs+=("$dir")
  mkdir -p "$dir"
  cp "$(pwd)/entrypoint.sh" "$dir/entrypoint.sh"
  chmod +x "$dir/entrypoint.sh"

  # Create mock binary that prints version and echoes args
  cat > "$dir/telegram-bot-api" <<'EOF'
#!/usr/bin/env sh
if [ "$1" = "--version" ]; then
  echo "Telegram Bot API Server mock 9.5"
  exit 0
fi
echo "MOCK telegram-bot-api invoked with args: $@"
exit 0
EOF
  chmod +x "$dir/telegram-bot-api"

  echo "$dir"
}

Automatic Cleanup

The test script uses a trap to remove temporary directories:

cleanup_dirs=()
trap 'rm -rf "${cleanup_dirs[@]+"${cleanup_dirs[@]}"}"' EXIT

Adding New Tests

To add a new test case:

Define the test function

Create a function that returns 0 on success, non-zero on failure:

test_my_new_feature() {
  local dir
  dir=$(setup_sandbox)
  output=$(cd "$dir" && TELEGRAM_API_ID=1 TELEGRAM_API_HASH=abc \
    TELEGRAM_MY_VAR=value ./entrypoint.sh 2>&1)
  echo "$output" | grep -F -q "--my-flag value"
}

Add a run_test call at the bottom of tests/run.sh:

run_test "my new feature" test_my_new_feature

Run and verify

Execute the test suite:

bash tests/run.sh

Example: Testing a New Environment Variable

Suppose you add support for TELEGRAM_VERBOSITY:

test_verbosity_flag() {
  local dir
  dir=$(setup_sandbox)
  output=$(cd "$dir" \
    && TELEGRAM_API_ID=1 TELEGRAM_API_HASH=abc \
       TELEGRAM_VERBOSITY=5 \
       ./entrypoint.sh 2>&1)
  echo "$output" | grep -F -q -- "--verbosity 5"
}

run_test "verbosity flag" test_verbosity_flag

Mock Binary Approach

The test suite uses a mock binary instead of the real telegram-bot-api executable: Advantages:

No Docker build required
Fast execution (< 1 second)
No network or Telegram credentials needed
Easy to validate exact arguments passed

Mock implementation (tests/run.sh:34-42):

cat > "$dir/telegram-bot-api" <<'EOF'
#!/usr/bin/env sh
if [ "$1" = "--version" ]; then
  echo "Telegram Bot API Server mock 9.5"
  exit 0
fi
echo "MOCK telegram-bot-api invoked with args: $@"
exit 0
EOF
chmod +x "$dir/telegram-bot-api"

The mock:

Handles --version flag for version checks
Echoes all arguments for validation
Always exits successfully

CI Test Execution

GitHub Actions runs the test suite automatically on:

Every push to main
Every pull request targeting main

Workflow: .github/workflows/test.yml

name: test

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  shell-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Run entrypoint.sh tests
        run: bash tests/run.sh

CI runs the same bash tests/run.sh command you use locally, ensuring consistent behavior.

Debugging Test Failures

If a test fails:

Run the test suite

Execute with verbose output:

bash -x tests/run.sh

Isolate the failing test

Comment out other run_test calls and re-run:

# run_test "missing API ID" test_missing_api_id
run_test "builds default args" test_builds_expected_args_defaults

Inspect sandbox manually

Modify the test to preserve the sandbox:

test_debug() {
  local dir
  dir=$(setup_sandbox)
  echo "Sandbox: $dir"
  cd "$dir"
  TELEGRAM_API_ID=1 TELEGRAM_API_HASH=abc ./entrypoint.sh
  # Comment out cleanup to inspect files
}

Best Practices

Keep tests isolated

Each test should use its own sandbox and not depend on other tests.

Test one thing

Each test function should validate a single behavior or scenario.

Use descriptive names

Test names should clearly describe what’s being validated.

Clean up resources

Always use the sandbox pattern to ensure proper cleanup.

Running Tests in Docker

While tests are designed to run without Docker, you can also run them inside a container:

docker run --rm -v "$(pwd):/workspace" -w /workspace alpine:3.23.3 sh -c '
  apk add --no-cache bash
  bash tests/run.sh
'

This validates behavior in the same Alpine environment used by the production image.

Overview

Setup & Deployment

Configuration

Operations

Migration

Development

Reference

Test Suite Overview

Running Tests Locally

Test Coverage

1. Missing API ID

2. Missing API Hash

3. Default Arguments

4. Custom Configuration

5. Local Mode Flag

6. Extra Arguments

7. Command Passthrough

Test Structure

`run_test(name, function)`

`setup_sandbox()`

Automatic Cleanup

Adding New Tests

Example: Testing a New Environment Variable

Mock Binary Approach

CI Test Execution

Debugging Test Failures

Best Practices

Keep tests isolated

Test one thing

Use descriptive names

Clean up resources

Running Tests in Docker

Build docs developers (and LLMs) love

Overview

Setup & Deployment

Configuration

Operations

Migration

Development

Reference

Documentation Index

​Test Suite Overview

​Running Tests Locally

​Test Coverage

​1. Missing API ID

​2. Missing API Hash

​3. Default Arguments

​4. Custom Configuration

​5. Local Mode Flag

​6. Extra Arguments

​7. Command Passthrough

​Test Structure

​run_test(name, function)

​setup_sandbox()

​Automatic Cleanup

​Adding New Tests

​Example: Testing a New Environment Variable

​Mock Binary Approach

​CI Test Execution

​Debugging Test Failures

​Best Practices

Keep tests isolated

Test one thing

Use descriptive names

Clean up resources

​Running Tests in Docker

Build docs developers (and LLMs) love

Test Suite Overview

Running Tests Locally

Test Coverage

1. Missing API ID

2. Missing API Hash

3. Default Arguments

4. Custom Configuration

5. Local Mode Flag

6. Extra Arguments

7. Command Passthrough

Test Structure

`run_test(name, function)`

`setup_sandbox()`

Automatic Cleanup

Adding New Tests

Example: Testing a New Environment Variable

Mock Binary Approach

CI Test Execution

Debugging Test Failures

Best Practices

Running Tests in Docker