Getting Started Development Help & Support

Developer Guide: Building & Testing

Developer guide for imgcompress: build and test locally with Docker, run unit and integration tests, set up the VS Code Dev Container, and simulate the full CI pipeline before pushing your changes.

DevelopmentGuide

Developer Guide

This guide covers how to run tests and builds locally so your contributions pass the same checks as CI. It also shows how to simulate the GitHub Actions pipeline exactly before you push.

1. VS Code Dev Container#

The easiest way to get a consistent dev environment is the VS Code Dev Container. It gives you a pre-configured Docker environment with all dependencies and extensions already installed.

How to use#

Open the project in VS Code.
Install the Dev Containers extension.
Click "Reopen in Container" when prompted (or run Dev Containers: Reopen in Container from the command palette).

What you get#

Pre-installed tools: Python 3.10+, Node.js, pnpm, and Docker CLI
Extensions: Python, Docker, ESLint, Playwright, and more
Port forwarding: port 3001 (app) and 5000 (backend) are forwarded automatically
Docker-in-Docker: you can build and run containers inside the dev container, which is required for integration and E2E tests

2. Local Development (Scripts)#

For faster iteration, I provide helper scripts that run tests directly in your local environment.

Prerequisites#

Python 3.10+ (with venv support)
Node.js & pnpm (for frontend and E2E)
Docker (for integration tests)

Unit and Integration Tests#

bash
# Run unit tests (backend)
./runUnitTests.sh

# Run integration tests
./runIntegrationTests.sh

End-to-End (E2E) Tests#

E2E tests need the backend and frontend running first. Open three terminals:

Terminal 1: ./runStartLocalBackend.sh
Terminal 2: ./runStartLocalFrontend.sh
Terminal 3: ./run-e2e.sh

See the Playwright E2E Testing Guide for debugging tips, targeted runs, and reports.

Docker Image Testing#

Use this script to test the production image locally. Handy for verifying that custom flags work without deploying a nightly build.

bash
PORT_HOST=8080 \
 DISABLE_LOGO=false \
 DISABLE_STORAGE_MANAGEMENT=true \
 ./runLocalDockerBuildTester.sh

Once running, open http://localhost:8080.

3. CI Simulation (Docker)#

To replicate the GitHub Actions CI environment exactly, use these Docker commands. If it passes here, it will pass in CI.

Build the Dev Container#

bash
docker buildx build -t devcontainer:local-test .devcontainer/

Backend Unit Tests#

bash
docker run --rm \
  --entrypoint /bin/sh \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$(pwd):/app/" \
  -e IS_RUNNING_IN_GITHUB_ACTIONS=true \
  --name devcontainer \
  devcontainer:local-test /app/runUnitTests.sh

Backend Integration Tests#

bash
docker run --rm \
  --entrypoint /bin/sh \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$(pwd):/app/" \
  -e IS_RUNNING_IN_GITHUB_ACTIONS=true \
  --name devcontainer \
  devcontainer:local-test /app/runIntegrationTests.sh

End-to-End (E2E) Tests#

Step 1: Build the ImgCompress image

bash
docker buildx build -t karimz1/imgcompress:local-test .

Step 2: Start the app

bash
docker run --rm -d \
  --network host \
  --name app \
  karimz1/imgcompress:local-test web

Step 3: Run E2E tests

bash
docker run --rm \
  --entrypoint /bin/sh \
  --network host \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$(pwd):/app/" \
  -e IS_RUNNING_IN_GITHUB_ACTIONS=true \
  -e PLAYWRIGHT_BASE_URL=http://localhost:5000 \
  --name devcontainer_e2e \
  devcontainer:local-test -c "/app/run-e2e.sh"

Common issue: broken pnpm lockfile after Dependabot merge#

Dependabot PRs that touch dependencies can leave a corrupted pnpm-lock.yaml when multiple lockfile changes are merged without a rebase.

Symptoms#

⚠️Warning

You may see an error like:

bash
broken lockfile at /workspaces/imgcompress/frontend:
The lockfile at "/workspaces/imgcompress/frontend/pnpm-lock.yaml" is broken:
duplicated mapping key (1307:3)

This means the lockfile has invalid YAML, usually from duplicated dependency entries.

Root cause#

Multiple Dependabot lockfile edits merged together without rebasing. pnpm validates YAML structure and fails immediately on duplicates.

Fix#

Do not hand-edit the lockfile. Regenerate it:

bash
cd /workspaces/imgcompress/frontend

# Remove corrupted artifacts
rm -rf node_modules
rm pnpm-lock.yaml

# Use the correct pnpm version
corepack enable
corepack prepare pnpm@9.15.0 --activate

# Regenerate
pnpm install

# Commit
git add pnpm-lock.yaml
git commit -m "chore: regenerate pnpm lockfile after dependabot merge"

Prevent it next time#

Rebase Dependabot PRs that modify pnpm-lock.yaml before merging, and let CI run pnpm install on the branch to catch issues early.

💡Need help?

Stuck on a step? Contact Support

Contributing

End-to-End Tests