Skip to content

README.md

Latest commit

 

History

History
145 lines (90 loc) · 4.71 KB

README.md

File metadata and controls

145 lines (90 loc) · 4.71 KB
Raw

Development Scripts

This directory contains scripts to streamline the development and testing of the eInk Layout Manager.

run_dev.sh

This script pulls the latest multi-arch development Docker image and starts a container for local testing.

Prerequisites

  • Docker: Must be installed and running.
  • Bash: Required to run the script.

Usage

Run the script from the project root directory:

./scripts/run_dev.sh

What it does:

  1. Pulls the Image: Fetches ghcr.io/stuart-c/addon-eink:dev from the GitHub Container Registry.
  2. Cleanup: Automatically stops and removes any previously running eink-dev container.
  3. Starts Container:
    • Port: Maps host port 8099 to container port 8099.
    • Persistence: Maps ./.data in the project root to /data in the container. Any database records or images created will be saved here.
  4. Browser: Automatically attempts to open http://localhost:8099 in your default browser.
  5. Logs: Starts following the container logs in your terminal. Press Ctrl+C to stop the logs and shut down the container.

run_tests.sh (Mandatory)

This script runs the full local test suite (Python lints, Python unit tests, and Frontend unit tests). Running this script is mandatory before submitting any code changes.

Usage

./scripts/run_tests.sh

Auto-provisioning

If the Python virtual environment (.venv) is not found, the script will automatically run ./scripts/make_venv.sh to provision it for you.

run_e2e.sh (Mandatory)

This script runs the end-to-end integration tests using Playwright. Running this script is mandatory for changes affecting the core application logic or API.

Usage

./scripts/run_e2e.sh

Warning

Parallel Run Warning: Running this script directly defaults to port 8099 and the ./eink/e2e/test_data_e2e directory. Running multiple instances without overrides will cause test failures and data corruption.

System Load: E2E tests are resource-intensive. Check your system load average (e.g., using uptime or top) before starting parallel runs to ensure your machine can handle the extra processes.

Auto-provisioning

Like run_tests.sh, this script will automatically provision the virtual environment and ensure Playwright browsers are installed if they are missing.

verify_all.sh

This is a comprehensive wrapper script that executes the full development pipeline in an isolated environment. It is recommended to run this script before pushing any significant changes.

Usage

./scripts/verify_all.sh

What it does:

  1. Isolation: Generates a random free port and a unique temporary data directory (.data_verify_XXXXXX) to ensure the verification process does not interfere with your local development data or other running services.
  2. Frontend Build: Runs ./scripts/build_frontend.sh.
  3. Unit Tests: Runs ./scripts/run_tests.sh (Python lints, unit tests, and Frontend unit tests).
  4. Backend Startup: Starts the backend application in the background using the generated port and temporary directory.
  5. E2E Tests: Runs ./scripts/run_e2e.sh against the freshly started background application.
  6. Cleanup: Automatically terminates the background backend process and removes the temporary data directory upon completion or if the script is interrupted.

make_venv.sh

A helper script used by the testing tools to create a Python virtual environment and initialise nodeenv with the correct Node.js version.

Usage

./scripts/make_venv.sh

build_frontend.sh

This script builds the frontend assets.

Usage

./scripts/build_frontend.sh

Auto-provisioning

If the Python virtual environment is not found, it will automatically run ./scripts/make_venv.sh.

run_app.sh

This script runs the backend application locally within the virtual environment.

Usage

./scripts/run_app.sh

Auto-provisioning

If the Python virtual environment is not found, it will automatically run ./scripts/make_venv.sh.

Persistence

This script runs the application with the DATA_DIR environment variable set to ./.data in the project root. This is where the SQLite database and image assets will be stored during local execution.

Troubleshooting and Cleanup

If an E2E test or the application is interrupted, it may leave a background Python process running on its allocated port.

Identifying Orphans

You can check if a process is still occupying a port:

lsof -i :8099

Manual Cleanup

To kill an orphaned backend process running on port 8099:

fuser -k 8099/tcp

Or use ps to find the app.main process and kill it manually.