Test plan from repo - ashleydavis/photosphere GitHub Wiki

Test plan: Smoke tests to run directly from the repo

Run the following commands from the CLI directory and verify expectations for:

  • Windows
  • Linux
  • MacOS

All commands (except those explicitly expected to fail) should return a non-error exit code 0.

Automated Execution

An automated smoke test script is available at apps/cli/smoke-tests.sh that implements all the tests below.

Show usage help:

cd photosphere/apps/cli
./smoke-tests.sh                    # Shows usage information
./smoke-tests.sh help               # Same as above

Run all tests:

./smoke-tests.sh all                # Run complete test suite (assumes executable built)
./smoke-tests.sh setup,all          # Build frontend and run complete test suite

Environment management:

./smoke-tests.sh setup              # Setup environment and build frontend
./smoke-tests.sh reset              # Clean up test artifacts and reset environment

Reset command functionality: The reset command provides comprehensive cleanup of test artifacts:

  • Removes test database directories (./test/test-db and variations)
  • Cleans up frontend build artifacts (pfe.zip)
  • Removes TypeScript build info (tsconfig.tsbuildinfo)
  • Shows directory contents after cleanup for verification
  • Safe operation - only removes known test artifacts

Useful when:

  • Tests fail partway through and leave artifacts
  • You want to ensure a completely clean testing environment
  • Debugging test issues that might be caused by leftover state
  • Switching between different test scenarios

Run individual tests:

./smoke-tests.sh create-database    # Test database creation
./smoke-tests.sh view-media         # Test media file analysis
./smoke-tests.sh add-single         # Test adding single file
./smoke-tests.sh 3                  # Same as above (by number)

Run multiple commands in sequence:

./smoke-tests.sh reset,setup,1,3    # Reset, setup, create DB, then test 3
./smoke-tests.sh setup,create-database,add-single  # Chain specific commands
./smoke-tests.sh 1,3,4,5            # Run tests 1, 3, 4, and 5 in sequence

Multiple commands functionality:

  • Use commas to separate commands (no spaces around commas)
  • Commands run in exact order specified
  • Each command must complete successfully before next command runs
  • Provides progress indication (Command 1/4, Command 2/4, etc.)
  • Shows comprehensive summary with total commands run and test results
  • Cannot use 'all' command in sequences (would be redundant)
  • Useful for custom workflows and debugging specific test combinations

Common multiple command patterns:

  • reset,setup,1 - Clean environment → prepare → create database
  • setup,1,3,4,5 - Full file testing workflow
  • reset,1,7 - Test database creation and overwrite protection
  • 1,3,4 - Database and file operations only (skip environment tests)

This script:

  • Automatically detects the platform (Linux/Mac/Windows)
  • Runs all tests sequentially with proper error handling
  • Supports running individual tests for debugging
  • Supports running multiple commands in sequence with comma separation
  • Provides colored output for easy result interpretation
  • Cleans up test artifacts automatically
  • Returns appropriate exit codes for CI/CD integration

Manual Test Steps

Setup

cd photosphere/apps/cli # Change to cli project.

rm -rf ./test/test-db # Clean up previous test run.

bun run build-fe-[linux|win|mac] # Build the frontend for your platform.

Note: Media processing tools (ImageMagick, ffmpeg, ffprobe) will be installed automatically when running commands with the --yes flag.

Enhanced Testing Workflow

CI/CD workflow (executable testing):

  1. Build executable first (bun run build-linux/win/mac)
  2. ./smoke-tests.sh all - Test the built executable

Development workflow:

  1. ./smoke-tests.sh reset - Clean up any previous test artifacts
  2. ./smoke-tests.sh setup,all - Build frontend and run all tests
  3. ./smoke-tests.sh reset - Clean up when done

Quick combined workflows:

./smoke-tests.sh setup,all          # Build and test everything
./smoke-tests.sh reset,setup,all    # Clean, build, and test everything

Debugging specific issues:

./smoke-tests.sh setup,1            # Build and create database
./smoke-tests.sh 3                  # Test specific functionality
./smoke-tests.sh reset              # Clean up

Testing built executable:

# After building with bun run build-linux/win/mac
./smoke-tests.sh all                # Test the executable directly

Create the database

Assumes

  • The directory is empty or doesn't yet exist.
bun run start -- init ./test/test-db

Check

  • Directory is created with .db folder and tree.dat
  • README.txt is created in asset db directory and in .db folder.
bun run start -- check ./test/test-db ../../test # No files have been added yet.

bun run start -- summary ./test/test-db # No files

bun run start -- ls ./test/test-db # No files

View local media files

bun run start -- info ../../test/

Check

  • Should show the details for multiple image and video files.

Add one file

bun run start -- add ./test/test-db ../../test/test.png # Adds 1 file.

Check

  • 1 file was added.
bun run start -- check ./test/test-db ../../test/test.png # 1 file already added.

bun run start -- summary ./test/test-db # 1 file

bun run start -- ls ./test/test-db # 1 file

Add same file

bun run start -- add ./test/test-db ../../test/test.png # Doesn't re-add the same file.

Check

  • Still only 1 file.
  • No new copy of the file was added.
bun run start -- summary ./test/test-db # 1 file

bun run start -- ls ./test/test-db # 1 file

Add multiple files

bun run start -- add ./test/test-db ../../test/multiple-images/ # Want to test with and without the trailing slash. Adds multiple files.

Check

  • Multiple new files were added.
bun run start -- check ./test/test-db ../../test/multiple-images/ # Multiple files already added.

bun run start -- summary ./test/test-db # Multiple files.

bun run start -- ls ./test/test-db # Multiple files.

Add same files

bun run start -- add ./test/test-db ../../test/multiple-images/ # Doesn't re-add the same files.

Check

  • No new files were added.
bun run start -- summary ./test/test-db # Multiple files.

bun run start -- ls ./test/test-db # Multiple files.

Can't create new database over existing

bun run start -- init ./test/test-db # Fails because asset db already exists.

Check

  • Command fails due to database already existing.
  • Returns non-zero exit code.

Run the UI

bun run start -- ui ./test/test-db

Check

  • UI server starts successfully
  • Web interface is accessible
  • Database files are served correctly
  • Note: This test requires manual verification and is typically skipped in automated CI/CD environments

Creating a database in the cloud

Note: These tests require valid AWS S3 credentials and are typically skipped in automated CI/CD environments.

Remove existing S3 configuration (if any):

rm -rf .photosphere.json

Remove the existing database in the cloud.

Create a new database:

bun run start -- init s3:test-bucket-1234/my-test-database-1

Check

  • Asks for configuration if there is none locally.
  • Database files are created in the S3 bucket.

Create another database:

bun run start -- init s3:test-bucket-1234/my-test-database-2

Check

  • This time it should remember the S3 configuration from before.

Fails to create existing database

Attempt to create the same database:

bun run start -- init s3:test-bucket-1234/my-test-database-1

Check

  • The command fails and displays an appropriate error message.
  • Returns non-zero exit code.

Test Automation Notes

  • The automated smoke test script skips S3/cloud tests as they require AWS credentials
  • The UI test is skipped in automated runs as it requires manual verification
  • All other tests are fully automated and validate both success and failure scenarios
  • The script provides detailed logging and cleanup for CI/CD integration