SuiteCRM Test Runner

A Node.js CLI tool to run verification tests or launch SuiteCRM server with Docker. Downloads ZIP files containing database dumps and patches, sets up the necessary files, and runs Docker containers with proper configuration.

Installation

npm install -g @originator/suitecrm-test-runner

Or use it locally in your project:

npm install @originator/suitecrm-test-runner
npx suitecrm-test-runner --help

Quick Start

Run Verification Tests

suitecrm-test-runner verify \
  -p ./verifier.py \
  -u https://example.com/test-data.zip

Launch SuiteCRM Server

suitecrm-test-runner suitecrm \
  -u https://example.com/test-data.zip

Commands

verify - Run Verification Tests

Runs your Python verifier script against a SuiteCRM database.

Required Options:

• -p, --python <path> - Path to Python verifier file
• -u, --url <url> - URL to zip file containing db_dump.sql and optionally suitecrm_diff.patch

Optional Options:

• --cleanup - Clean up temporary files after execution

Example:

suitecrm-test-runner verify \
  -p ./my-verifier.py \
  -u https://example.com/data.zip \
  --cleanup

suitecrm - Launch SuiteCRM Server

Starts a SuiteCRM server with your database dump and optional patch applied.

Required Options:

• -u, --url <url> - URL to zip file containing db_dump.sql and optionally suitecrm_diff.patch

Optional Options:

• --cleanup - Clean up temporary files after execution

Example:

suitecrm-test-runner suitecrm \
  -u https://example.com/data.zip 

If you don't specify a port, the tool will automatically:

• Find an available random port
• Launch the SuiteCRM server
• Wait for it to be ready
• Open your default browser to http://localhost:<port>

ZIP File Structure

The zip file should contain:

• db_dump.sql (required) - SQL database dump file
• suitecrm_diff.patch (optional) - SuiteCRM patch file

Files can be in any directory within the zip file - the tool will find them recursively.

How It Works

Verify Command

1. Creates a temporary workspace
2. Downloads the ZIP file from the URL
3. Extracts db_dump.sql and optional suitecrm_diff.patch
4. Copies your Python verifier file
5. Runs Docker with volume mounts:
   • /app/verifier.py - Your verification script
   • /app/db_dump.sql - Database dump
   • /app/suitecrm_diff.patch - Patch file (if present)
6. Executes python3 test.py with your database credentials
7. Formats and displays the JSON results (success, score, explanation)
8. Cleans up containers and temporary files

SuiteCRM Command

1. Creates a temporary workspace
2. Downloads the ZIP file from the URL
3. Extracts db_dump.sql and optional suitecrm_diff.patch
4. Finds an available port (or uses the one you specify)
5. Runs Docker with:
   • Port mapping: <host-port>:80
   • Volume mounts for dump and patch files
6. Applies the patch to SuiteCRM (if provided)
7. Imports the database dump
8. Starts Apache web server
9. Waits for the server to be ready
10. Opens your default browser automatically
11. Stops the container when you exit (Ctrl+C)

Requirements

• Node.js 14.0.0 or higher
• Docker installed and running
• Docker image built and available (default: runner)

Building the Docker Image

Before using this tool, you need to build the Docker image:

cd runner
docker build -t runner .

The Docker image should:

• Have SuiteCRM installed at /apps/suitecrm
• Have MySQL server configured
• Include test.py and suitecrm.py scripts in /app
• Use /start_mysql_and_run.sh as the entrypoint

Output Format

Verify Command Output

The verify command displays formatted results:

============================================================
TEST RESULTS
============================================================
Success: ✓ TRUE
Score: 1
Explanation: Task completed successfully: all requirements met.
============================================================

SuiteCRM Command Output

The suitecrm command shows:

• Selected port number
• Container launch status
• Server readiness confirmation
• Browser opening notification

Error Handling

• If the ZIP file is missing required files, the tool will error with a clear message
• If Docker is not running, you'll get a helpful error
• If a port is already in use, the tool will select a random available port
• Containers are automatically stopped when you exit the CLI (Ctrl+C)

License

ISC

Author

Originator Inc