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 databasesetup,1,3,4,5
- Full file testing workflowreset,1,7
- Test database creation and overwrite protection1,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):
- Build executable first (
bun run build-linux/win/mac
) ./smoke-tests.sh all
- Test the built executable
Development workflow:
./smoke-tests.sh reset
- Clean up any previous test artifacts./smoke-tests.sh setup,all
- Build frontend and run all tests./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