Installation Guide

Complete guide for installing and setting up socialseed-e2e on your system.

Table of Contents

System Requirements
Quick Install
Step-by-Step Installation
Virtual Environment Setup
Development Installation
Playwright Browser Installation
Verification
Platform-Specific Notes
Troubleshooting
Common Issues
Next Steps

System Requirements

Minimum Requirements

Python: 3.9 or higher (3.9, 3.10, 3.11, 3.12 supported)
pip: 21.0 or higher
Operating System:
- Linux (Ubuntu 20.04+, CentOS 8+, Debian 10+)
- macOS (10.15 Catalina or higher)
- Windows (Windows 10 or higher)
Memory: 2 GB RAM minimum (4 GB recommended)
Disk Space: 500 MB for installation + 200 MB for Playwright browsers

Optional Requirements

Git: For development installation
Virtual Environment Tool: venv (included in Python 3.3+) or virtualenv
Node.js: 16+ (required for some Playwright features)

Check Your Python Version

python --version
# or
python3 --version

Expected output: Python 3.9.x or higher

If you don’t have Python 3.9+, download it from python.org.

Quick Install

For experienced users who want to get started immediately:

# Install the package
pip install socialseed-e2e

# Install Playwright browsers
playwright install chromium

# Verify installation
e2e doctor

Step-by-Step Installation

1. Create a Virtual Environment (Recommended)

Using a virtual environment keeps your project dependencies isolated.

Linux/macOS

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate

# Your prompt should now show (venv)

Windows

# Create virtual environment
python -m venv venv

# Activate virtual environment (Command Prompt)
venv\Scripts\activate.bat

# Or PowerShell
venv\Scripts\Activate.ps1

2. Install socialseed-e2e

With your virtual environment activated:

pip install socialseed-e2e

This will install:

socialseed-e2e framework
Playwright for HTTP testing
Pydantic for data validation
PyYAML for configuration
Rich for terminal output
Click for CLI
All other dependencies

3. Install Playwright Browsers

Playwright requires browser binaries to perform HTTP testing:

# Install Chromium (recommended, smaller footprint)
playwright install chromium

# Or install all browsers (Chromium, Firefox, WebKit)
playwright install

Download Size:

Chromium only: ~150 MB
All browsers: ~400 MB

Installation Time: 1-3 minutes depending on your connection

4. Verify Installation

Run the built-in doctor command to check your setup:

e2e doctor

Expected output:

🔍 Running system checks...

✓ Python version: 3.12.0
✓ socialseed-e2e: 0.1.0
✓ Playwright: 1.40.0
✓ Chromium browser: Installed
✓ Configuration: Ready

🎉 All checks passed! Your system is ready.

Virtual Environment Setup

Why Use Virtual Environments?

Isolation: Dependencies don’t conflict with other projects
Reproducibility: Easy to recreate the same environment
Clean System: No global package pollution
Version Control: requirements.txt or pyproject.toml tracks dependencies

Creating Virtual Environments

Using venv (Built-in)

# Create
python -m venv myproject-env

# Activate
source myproject-env/bin/activate  # Linux/macOS
myproject-env\Scripts\activate     # Windows

# Deactivate
deactivate

Using virtualenv

# Install virtualenv
pip install virtualenv

# Create
virtualenv myproject-env

# Activate
source myproject-env/bin/activate  # Linux/macOS
myproject-env\Scripts\activate     # Windows

Using conda

# Create
conda create -n socialseed-e2e python=3.11

# Activate
conda activate socialseed-e2e

# Install package
pip install socialseed-e2e

Best Practices

Name your environment: Use descriptive names like my-api-tests
Add to .gitignore: Don’t commit virtual environment folders
Document dependencies: Keep a requirements.txt or use pyproject.toml
Pin versions: Specify versions for reproducibility

Development Installation

If you want to contribute to socialseed-e2e or modify the source code:

1. Clone the Repository

git clone https://github.com/daironpf/socialseed-e2e.git
cd socialseed-e2e

2. Create Virtual Environment

python -m venv venv
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate     # Windows

3. Install in Editable Mode

pip install -e ".[dev]"

This installs:

Package in editable mode (changes reflect immediately)
Development dependencies (pytest, black, flake8, mypy, etc.)
All runtime dependencies

4. Install Playwright Browsers

playwright install chromium

5. Run Tests

pytest

6. Verify Development Setup

e2e doctor
e2e --version

Playwright Browser Installation

Playwright browsers are essential for HTTP testing. Here’s how to manage them:

Install Specific Browsers

# Chromium only (recommended for API testing)
playwright install chromium

# Firefox
playwright install firefox

# WebKit
playwright install webkit

# All browsers
playwright install

Update Browsers

# Update all installed browsers to latest versions
playwright install --with-deps chromium

Uninstall Browsers

# Remove all browsers
playwright uninstall

# Remove specific browser
playwright uninstall chromium

Check Browser Versions

# List installed browsers
playwright show-browsers

System Dependencies

Playwright may require system dependencies on Linux:

Ubuntu/Debian

playwright install-deps chromium

Or manually:

sudo apt-get update
sudo apt-get install -y libglib2.0-0 \
    libnss3 \
    libnspr4 \
    libatk1.0-0 \
    libatk-bridge2.0-0 \
    libcups2 \
    libdrm2 \
    libdbus-1-3 \
    libxcb1 \
    libxkbcommon0 \
    libx11-6 \
    libxcomposite1 \
    libxdamage1 \
    libxext6 \
    libxfixes3 \
    libxrandr2 \
    libgbm1 \
    libpango-1.0-0 \
    libcairo2 \
    libasound2

CentOS/RHEL/Fedora

sudo yum install -y alsa-lib \
    atk \
    cups-libs \
    dbus-libs \
    expat \
    libXcomposite \
    libXcursor \
    libXdamage \
    libXext \
    libXi \
    libXrandr \
    libXtst \
    libdrm \
    libxcb \
    libxkbcommon \
    mesa-libgbm \
    nss \
    pango

Verification

Using e2e doctor

The e2e doctor command checks your entire setup:

e2e doctor

Checks performed:

Python version compatibility
socialseed-e2e installation
Playwright installation
Browser binaries
CLI functionality

Manual Verification

# Check Python version
python --version

# Check package installation
pip show socialseed-e2e

# Check Playwright
playwright --version

# Check CLI
which e2e
e2e --help

# Test basic functionality
e2e init test-project
cd test-project
e2e config

Expected Output

$ python --version
Python 3.12.0

$ pip show socialseed-e2e
Name: socialseed-e2e
Version: 0.1.0
Summary: Framework E2E para testing de APIs REST con Playwright
...

$ playwright --version
Version 1.40.0

$ e2e doctor
🔍 Running system checks...
✓ Python version: 3.12.0
✓ socialseed-e2e: 0.1.0
✓ Playwright: 1.40.0
✓ Chromium browser: Installed
✓ Configuration: Ready
🎉 All checks passed! Your system is ready.

Platform-Specific Notes

Linux

Ubuntu/Debian

# Install system dependencies for Playwright
sudo apt-get update
sudo apt-get install -y libnss3 libatk-bridge2.0-0 libxcomposite1

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install
pip install socialseed-e2e
playwright install chromium

CentOS/RHEL/Fedora

# Install system dependencies
sudo yum install -y atk cups-libs libXcomposite libXcursor

# Install Python 3.9+ if not available
sudo yum install -y python39 python39-pip

# Create virtual environment
python3.9 -m venv venv
source venv/bin/activate

# Install
pip install socialseed-e2e
playwright install chromium

macOS

Using Homebrew

# Install Python if needed
brew install python@3.11

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install
pip install socialseed-e2e
playwright install chromium

Manual Installation

# Download Python from python.org
# Install normally

# Open Terminal
python3 -m venv venv
source venv/bin/activate
pip install socialseed-e2e
playwright install chromium

Windows

Using Command Prompt

:: Create virtual environment
python -m venv venv

:: Activate
venv\Scripts\activate.bat

:: Install
pip install socialseed-e2e
playwright install chromium

Using PowerShell

# Create virtual environment
python -m venv venv

# Activate
venv\Scripts\Activate.ps1

# Install
pip install socialseed-e2e
playwright install chromium

Windows-Specific Issues

If you see execution policy errors in PowerShell:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Troubleshooting

Installation Failures

Permission Denied

Problem: Permission denied when installing

Solution 1: Use --user flag

pip install --user socialseed-e2e

Solution 2: Use virtual environment (recommended)

python -m venv venv
source venv/bin/activate
pip install socialseed-e2e

Solution 3: Use sudo (not recommended)

sudo pip install socialseed-e2e  # Linux/macOS only

Network Issues

Problem: Connection timeout or SSL certificate verify failed

Solution 1: Use trusted host

pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org socialseed-e2e

Solution 2: Configure proxy

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
pip install socialseed-e2e

Solution 3: Use mirror (China users)

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple socialseed-e2e

Playwright Issues

Browser Installation Fails

Problem: playwright install fails with download errors

Solution 1: Check internet connection

ping playwright.azureedge.net

Solution 2: Set download host (China users)

set PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright
playwright install chromium

Solution 3: Manual download

# Download browser manually and place in correct location
# Location: ~/.cache/ms-playwright/ on Linux/macOS
# Location: %USERPROFILE%\AppData\Local\ms-playwright\ on Windows

Missing System Dependencies

Problem: Chromium fails to launch with missing library errors

Solution: Install system dependencies

# Ubuntu/Debian
sudo apt-get install -y libnss3 libatk-bridge2.0-0 libxcomposite1 libxdamage1

# Or use Playwright's automatic installer
playwright install-deps chromium

Python Version Issues

Python Not Found

Problem: python: command not found

Solution 1: Use python3

python3 -m pip install socialseed-e2e

Solution 2: Create alias

alias python=python3
python -m pip install socialseed-e2e

Wrong Python Version

Problem: Package requires Python 3.9+, you have 3.8

Solution: Install Python 3.9+

# Ubuntu/Debian
sudo apt-get install python3.11 python3.11-venv python3.11-pip

# macOS
brew install python@3.11

# Windows
# Download from python.org

Virtual Environment Issues

Cannot Activate

Problem: source venv/bin/activate doesn’t work

Solution 1: Check if venv exists

ls -la venv/bin/activate

Solution 2: Use absolute path

source /full/path/to/venv/bin/activate

Solution 3: Check permissions

chmod +x venv/bin/activate

Wrong Python in venv

Problem: Virtual environment uses system Python

Solution: Recreate with correct Python

rm -rf venv
python3.11 -m venv venv
source venv/bin/activate

Common Issues

ImportError: No module named ‘socialseed_e2e’

Cause: Package not installed or installed in wrong environment

Solution:

# Check which Python you're using
which python

# Check if package is installed
pip list | grep socialseed

# Install in current environment
pip install socialseed-e2e

e2e command not found

Cause: CLI not in PATH

Solution 1: Activate virtual environment

source venv/bin/activate

Solution 2: Use full path

/path/to/venv/bin/e2e

Solution 3: Reinstall with –force-reinstall

pip install --force-reinstall socialseed-e2e

Playwright browser not found

Cause: Browsers not installed or wrong location

Solution:

# Reinstall browsers
playwright uninstall
playwright install chromium

# Check location
playwright show-browsers

# Verify e2e doctor output
e2e doctor

SSL Certificate Errors

Cause: Outdated certificates or corporate proxy

Solution 1: Update certificates

# macOS
brew install ca-certificates

# Ubuntu/Debian
sudo update-ca-certificates

Solution 2: Disable SSL verification (temporary, not recommended for production)

pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org socialseed-e2e

ModuleNotFoundError on Import

Cause: Missing dependencies or circular import

Solution:

# Reinstall with all dependencies
pip install --force-reinstall --no-cache-dir socialseed-e2e

# Or in development mode
git clone https://github.com/daironpf/socialseed-e2e.git
cd socialseed-e2e
pip install -e ".[dev]"

Tests Fail After Installation

Cause: Incomplete setup or missing browsers

Solution:

# Full reinstall
pip uninstall socialseed-e2e -y
pip cache purge
pip install socialseed-e2e
playwright install chromium

# Verify
e2e doctor
pytest --version

Next Steps

After successful installation:

Quick Start Guide - Create your first test in 5 minutes
Configuration - Learn about e2e.conf options
Writing Tests - Test writing patterns and best practices
CLI Reference - Complete CLI command reference

Quick Test

# Initialize a test project
e2e init my-first-test
cd my-first-test

# Check configuration
e2e config

# Run tests (if you have any)
e2e run

Getting Help

Documentation: Full Documentation
Issues: GitHub Issues
Discussions: GitHub Discussions

Still having issues?

Run e2e doctor and share the output when opening an issue.