[test] docker suite for testing

3 files changed, 307 insertions, 0 deletions

diff --git a/test/Dockerfile b/test/Dockerfile
new file mode 100644
index 0000000..31debe0
--- /dev/null
+++ b/test/Dockerfile
@@ -0,0 +1,20 @@
+FROM ubuntu:22.04
+
+# Install required packages
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    xvfb \
+    imagemagick \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create app directory
+WORKDIR /app
+
+# Copy your library and any dependencies
+COPY . /app
+
+# Make sure binaries are executable
+RUN chmod +x /app/*
+
+# Accept program name as argument and run with virtual framebuffer
+ENTRYPOINT ["xvfb-run", "-a"]
\ No newline at end of file
diff --git a/test/README.md b/test/README.md
new file mode 100644
index 0000000..3f77c6b
--- /dev/null
+++ b/test/README.md
@@ -0,0 +1,168 @@
+# Framebuffer Graphics Library Testing
+
+This directory contains Docker-based testing setup for your Linux framebuffer graphics library. Test your programs in an isolated environment without affecting your main system.
+
+## Quick Start
+
+1. **Setup** (one-time):
+   ```bash
+   chmod +x test.sh
+   ./test.sh build
+   ```
+
+2. **Run your tests**:
+   ```bash
+   ./test.sh run ./your_program
+   ```
+
+## Prerequisites
+
+- Docker installed and running
+- Your compiled graphics programs in this directory
+
+## Files
+
+- `Dockerfile` - Container configuration with framebuffer support
+- `test.sh` - Management script for Docker operations
+- Your compiled programs and library files
+
+## Usage
+
+### Build Test Environment
+```bash
+./test.sh build
+```
+Creates the Docker image with virtual framebuffer support.
+
+### Run Programs
+```bash
+# Basic usage
+./test.sh run ./my_graphics_test
+
+# With arguments
+./test.sh run ./demo --width 800 --height 600
+
+# Full path
+./test.sh run /app/bin/test_suite
+```
+
+### Management Commands
+```bash
+./test.sh stop          # Stop any running test
+./test.sh clean         # Remove container and image
+./test.sh rebuild       # Clean build from scratch
+./test.sh shell         # Interactive debugging shell
+./test.sh help          # Show all commands
+```
+
+## How It Works
+
+1. **Virtual Framebuffer**: Uses `xvfb` to create a virtual display
+2. **Isolated Environment**: Your programs run in Ubuntu container
+3. **Live Code**: Your directory is mounted, so code changes are immediate
+4. **No Graphics Hardware**: No GPU drivers or display required
+
+## Directory Structure
+
+```
+your-project/
+├── Dockerfile          # Container setup
+├── test.sh            # Test runner script
+├── README.md          # This file
+├── your_library.so    # Your graphics library
+├── test_program1      # Compiled test program
+├── test_program2      # Another test program
+└── src/               # Source code (optional)
+```
+
+## Testing Workflow
+
+1. **Develop**: Write and compile your graphics programs
+2. **Test**: Run `./test.sh run ./program_name`
+3. **Debug**: Use `./test.sh shell` for interactive debugging
+4. **Iterate**: Make changes and test again (no rebuild needed)
+
+## Troubleshooting
+
+### Build Issues
+```bash
+./test.sh rebuild       # Clean rebuild
+```
+
+### Permission Problems
+```bash
+chmod +x test.sh        # Make script executable
+chmod +x ./your_program # Make test programs executable
+```
+
+### Container Won't Stop
+```bash
+docker kill fb-test-runner  # Force stop
+./test.sh clean            # Clean everything
+```
+
+### Debug Inside Container
+```bash
+./test.sh shell
+# Now you're inside the container
+ls -la /app
+./your_program --debug
+exit
+```
+
+## Advanced Usage
+
+### Custom Framebuffer Size
+Modify the Dockerfile to set specific display dimensions:
+```dockerfile
+ENV DISPLAY=:99
+ENV XVFB_RES=1920x1080x24
+```
+
+### Capture Screenshots
+Add to your test programs:
+```bash
+# Inside container
+import -window root screenshot.png
+```
+
+### Multiple Test Runs
+```bash
+for test in test_*.exe; do
+    ./test.sh run ./$test
+done
+```
+
+## Performance Notes
+
+- **Fast startup**: Containers start instantly
+- **Low overhead**: Minimal resource usage
+- **Quick iteration**: Code changes don't require rebuilds
+- **Parallel testing**: Can run multiple containers
+
+## Integration with CI/CD
+
+Add to your build pipeline:
+```yaml
+# Example GitHub Actions
+- name: Test Graphics Library
+  run: |
+    chmod +x test.sh
+    ./test.sh build
+    ./test.sh run ./test_suite
+```
+
+## Cleanup
+
+When done testing:
+```bash
+./test.sh clean         # Remove everything
+# Or just let Docker clean up automatically
+```
+
+## Tips
+
+- Keep your test programs in the main directory for easy access
+- Use descriptive names for test programs: `test_rendering.exe`, `demo_shapes.exe`
+- The container has full Ubuntu tools available for debugging
+- Virtual framebuffer works with most graphics operations your library performs
diff --git a/test/test.sh b/test/test.sh
new file mode 100644
index 0000000..2eb0899
--- /dev/null
+++ b/test/test.sh
@@ -0,0 +1,119 @@
+#!/bin/bash
+
+IMAGE_NAME="fb-test"
+CONTAINER_NAME="fb-test-runner"
+
+show_help() {
+    echo "Usage: $0 <command> [program_name]"
+    echo ""
+    echo "Commands:"
+    echo "  build           Build the Docker image"
+    echo "  run <program>   Run a program in the container"
+    echo "  stop            Stop running container"
+    echo "  clean           Remove container and image"
+    echo "  rebuild         Clean and build fresh"
+    echo "  shell           Start interactive shell in container"
+    echo ""
+    echo "Examples:"
+    echo "  $0 build"
+    echo "  $0 run ./my_graphics_test"
+    echo "  $0 run /app/test_program arg1 arg2"
+    echo "  $0 stop"
+    echo "  $0 clean"
+}
+
+build_image() {
+    echo "Building Docker image..."
+    docker build -t $IMAGE_NAME .
+    if [ $? -eq 0 ]; then
+        echo "✓ Image built successfully"
+    else
+        echo "✗ Build failed"
+        exit 1
+    fi
+}
+
+run_program() {
+    if [ -z "$1" ]; then
+        echo "Error: No program specified"
+        echo "Usage: $0 run <program> [args...]"
+        exit 1
+    fi
+    
+    echo "Running program: $@"
+    docker run --rm \
+        --name $CONTAINER_NAME \
+        -v $(pwd):/app \
+        $IMAGE_NAME "$@"
+}
+
+stop_container() {
+    echo "Stopping container..."
+    docker stop $CONTAINER_NAME 2>/dev/null
+    if [ $? -eq 0 ]; then
+        echo "✓ Container stopped"
+    else
+        echo "No running container found"
+    fi
+}
+
+clean_all() {
+    echo "Cleaning up..."
+    
+    # Stop container if running
+    docker stop $CONTAINER_NAME 2>/dev/null
+    
+    # Remove container if exists
+    docker rm $CONTAINER_NAME 2>/dev/null
+    
+    # Remove image
+    docker rmi $IMAGE_NAME 2>/dev/null
+    
+    echo "✓ Cleanup complete"
+}
+
+rebuild() {
+    echo "Rebuilding..."
+    clean_all
+    build_image
+}
+
+start_shell() {
+    echo "Starting interactive shell..."
+    docker run --rm -it \
+        --name $CONTAINER_NAME \
+        -v $(pwd):/app \
+        --entrypoint /bin/bash \
+        $IMAGE_NAME
+}
+
+# Main command handling
+case "$1" in
+    "build")
+        build_image
+        ;;
+    "run")
+        shift
+        run_program "$@"
+        ;;
+    "stop")
+        stop_container
+        ;;
+    "clean")
+        clean_all
+        ;;
+    "rebuild")
+        rebuild
+        ;;
+    "shell")
+        start_shell
+        ;;
+    "help"|"-h"|"--help"|"")
+        show_help
+        ;;
+    *)
+        echo "Unknown command: $1"
+        show_help
+        exit 1
+        ;;
+esac