# pytest-cream

**The cream of test execution** - smooth pytest workflows with intelligent orchestration.

pytest-cream is a Python package designed to streamline the process of fetching tests from repositories, running them with advanced dependency management, and gathering statistics for parallel execution.

## Features
- Fetch tests from remote repositories or local directories
- Advanced dependency management with custom installation commands
- Support for uv, poetry, pip, and other package managers
- Python version control for project compatibility
- Parallel test execution with intelligent orchestration
- Duration statistics and performance optimization
- Environment isolation for complex projects (Rust extensions, etc.)

## Installation

```bash
pip install pytest-cream
```

## Usage

### Basic Usage
```bash
# Run tests with standard dependency installation
pytest-cream quick-run --repo owner/project --branch main --ws ~/workspace

# Use custom installation commands for complex projects
pytest-cream quick-run --repo owner/project --branch main \
  --install-cmd "uv sync --extra cpu" \
  --python 3.10 \
  --ws ~/workspace
```

### Advanced Usage
```bash
# Multiple installation commands with fallback
pytest-cream quick-run --repo owner/complex-project --branch main \
  --install-cmd "uv sync --extra gpu; pip install torch" \
  --install-fallback "pip install -e ." \
  --python 3.11 \
  --ws ~/workspace

# Exclude problematic tests
pytest-cream quick-run --repo owner/project --branch main \
  --exclude-tests "test_slow.py,test_integration/" \
  --ws ~/workspace
```

### Original Quick Commands
```bash
# Fetch tests only
pytest-cream fetch --branch dev

# Run collected tests
pytest-cream run --all

# Filter by duration
pytest-cream filter --threshold 0.5
```

## Command Line Options

### Basic Options:
- `--repo`: Repository to test (owner/repo or URL)
- `--branch`: Branch to test
- `--ws` / `--workspace`: Directory to use as workspace
- `--threshold`: Duration threshold in seconds for splitting long/short tests (default: 1.0)
- `--workers`: Number of parallel workers for short tests (default: 4)

### Installation Options:
- `--install-repo`: Repository to install code from before running tests
- `--install-branch`: Branch to install from
- `--install-mode`: How to install (`pip`, `editable`, `wheel`)
- `--install-cmd`: Custom install command (overrides `--install-mode`)
- `--install-fallback`: Fallback to standard installation if custom command fails

### Test Execution Options:
- `--python`: Python executable to use (e.g., `python3.10`, `/usr/bin/python3.11`)
- `--exclude-tests`: Comma-separated patterns of test files/directories to exclude

## Installation Modes

When using `--install-repo`, you have several options:

### Standard Modes:
- `pip`: Direct install from git+https URL (fastest)
- `editable`: Clone repository and install in editable mode (for development)
- `wheel`: Build wheel and install (most reproducible)

### Custom Commands:
Use `--install-cmd` for complex dependency management that standard modes can't handle:

```bash
# uv with extras
--install-cmd "uv sync --extra cpu"

# Poetry with multiple extras
--install-cmd "poetry install --extras dev,test"

# pip with specific requirements file
--install-cmd "pip install -r requirements-dev.txt"

# Conda environment setup
--install-cmd "conda env update -f environment.yml"
```

**Note**: `--install-cmd` overrides `--install-mode` when provided. The command runs in the cloned repository directory.

### Usage Priority:
1. If `--install-cmd` is provided → Use custom command
2. If `--install-uv` is provided → Use uv instead of pip
3. Otherwise → Use standard `--install-mode` (pip/editable/wheel)

## Troubleshooting

### Python Version Issues
Some projects require specific Python versions, especially those with Rust extensions or compiled components:

```bash
# Use Python 3.10 for projects with Rust extensions
pytest-cream quick-run \
  --repo owner/rust-project \
  --python python3.10

# Use Python 3.11 for newer projects
pytest-cream quick-run \
  --repo owner/modern-project \
  --python python3.11
```

**Common Python version issues:**
- Rust extensions often require Python 3.10 or specific versions
- Some packages may not be compatible with Python 3.13+
- Use `--python` to specify the exact Python executable to use

### Excluding Problematic Tests
When some tests fail due to missing dependencies or environment issues:

```bash
# Exclude specific test files
--exclude-tests "tests/test_integration.py,tests/test_slow.py"

# Exclude test directories
--exclude-tests "tests/integration,tests/gpu"
```

### Pip Issues
If you encounter "No module named pip" errors when using virtualenv contexts, try using the `--install-uv` flag to use [uv](https://github.com/astral-sh/uv) instead of pip:

```bash
pytest-cream quick-run --install-repo owner/repo --install-uv --install-mode editable
```

This requires [uv](https://github.com/astral-sh/uv) to be installed on your system.

### Custom Command Issues
If your `--install-cmd` fails:

1. **Check the command works manually**:
   ```bash
   git clone https://github.com/owner/repo
   cd repo
   uv sync --extra cpu  # or your command
   ```

2. **Common fixes**:
   - For uv: Ensure `pyproject.toml` has the required extras defined
   - For Poetry: Make sure `pyproject.toml` exists and has proper dependencies
   - For build errors: Check if system dependencies (like Rust, C compilers) are needed

3. **Debugging**: Check the workspace directory for logs and cloned repository to investigate build issues

## License
MIT License