pCloud Sync Test Suite

Automated test suite for testing pCloud's sync functionality.

This test suite supports two testing modes:

• Drive Mode: Tests with mounted virtual drive
• Sync Folder Mode: Tests with both a mounted virtual drive and a regular folder synced via pCloud app

What It Tests

The tests create files locally and verify they sync correctly with the cloud (and vice versa). SHA1 checksums are used to verify data integrity.

Project Structure

fstests/
├── tests/                          # Test suite
│   ├── conftest.py                 # Shared pytest fixtures
│   ├── drive/                      # Drive mode tests
│   │   └── conftest.py             # Drive-specific fixtures (VirtualDriveHelper)
│   ├── sync/                       # Sync Folder mode tests
│   │   └── conftest.py             # Sync-specific fixtures (SyncFolderHelper)
├── utils/                          # Helper utilities
│   ├── pcloud_helper.py            # pCloud API wrapper
│   ├── file_operations.py          # Local file operations hepler
│   ├── virtual_drive_helper.py     # Virtual drive helper
│   ├── sync_folder_helper.py       # Sync folder helper
│   ├── test_helper.py              # Base class for folder helpers
│   └── test_context.py             # A helper used by each test
├── .env.example                    # Example configuration
├── requirements.txt                # Python dependencies
└── pytest.ini                      # Pytest configuration

Setup

2. Install Python Dependencies

macOS/Linux:

python -m venv venv
chmod +x venv/bin/activate # If file was just created
source venv/bin/activate
pip install -r requirements.txt

Windows PowerShell:

python -m venv venv
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser # To allow script execution
venv\Scripts/Activate.ps1
pip install -r requirements.txt

3. Configuration

Create a .env file:

cp .env.example .env

Edit .env and fill in the required values:

# pCloud Configuration
PCLOUD_AUTH_TOKEN=your_auth_token_here
PCLOUD_LOCATION_ID=us  # 'us' or 1 for US, 'eu' or 2 for European servers

# pCloud Drive Path (where your drive is mounted)
DRIVE_PATH=path_to_pcloud_drive

# For Sync Folder mode:
SYNC_FOLDER_LOCAL_PATH=path_to_local_sync_folder
SYNC_FOLDER_REMOTE_PATH=path_in_pcloud_account

# Test folder name (will be created in root of drive)
TEST_FOLDER=test-sync-automation

# Clean test folder at start of run (default: false)
# Useful when a previous run failed to clean up
CLEAN_TEST_FOLDER=false

# Sync timeout in seconds (default: 120)
SYNC_TIMEOUT=120

# Skip GB-sized file tests (default: true)
SKIP_GB_TESTS=true

Using Environment Variables (CI/Automation)

All configuration can be provided as environment variables instead of (or in addition to) a .env file. Environment variables take precedence over .env file values — if both are set, the environment variable wins. If all required variables are set in the environment, no .env file is needed at all.

Inline example:

PCLOUD_AUTH_TOKEN=xxx DRIVE_PATH=/mnt/pcloud pytest tests/drive/

CI script example:

export PCLOUD_AUTH_TOKEN="$CI_PCLOUD_TOKEN"
export PCLOUD_LOCATION_ID=eu
export DRIVE_PATH=/mnt/pcloud
pytest tests/drive/ -m "essential"

How to Get Your Auth Token:

Option 1 - Via Browser:

1. Open a new tab
2. Enter https://api.pcloud.com/userinfo?getauth=1&username=USERNAME&password=PASSWORD where USERNAME and PASSWORD should be replaced with your email and password. If your account is European, use https://eapi.pcloud.com.
3. Press Enter. You'll receive a JSON response. Inside there will be an auth field with your token.

Option 2 - Via Python:

import requests
response = requests.get(
    'https://api.pcloud.com/userinfo',
    params={'getauth': 1, 'username': 'your_email', 'password': 'your_password'}
)
print(response.json()['auth'])

Running Tests

Quick Start

macOS/Linux:

# Activate virtual environment
source venv/bin/activate

# Run all tests
pytest

# Or use the convenience script
./run_tests.sh

Windows Powershell:

# Activate virtual environment
venv\Scripts/Activate.ps1

# Run all tests
pytest

# Or use the convenience script
./RunTests.ps1

Test Suites

Tests are organized by directory (drive vs sync) and classified with pytest markers into speed tiers:

Speed tiers (mutually exclusive per test):

• essential — fast, high-value tests for per-commit runs
• extended — thorough tests for nightly/PR runs
• stress — heavy, large-scale tests for weekly/manual runs
• manual — requires human intervention

Area markers (stackable):

• filesystem — all drive-mode tests (in tests/drive/)
• sync — all sync-folder-mode tests (in tests/sync/)

Examples:

# Per-commit: fast tests only
pytest -m "essential"

# Per-commit: fast drive tests only
pytest tests/drive/ -m "essential"

# Nightly: everything except stress and manual
pytest -m "not stress and not manual"

# Weekly stress run
pytest -m "stress"

# All sync tests
pytest tests/sync/

# Combine freely
pytest -m "extended and filesystem"

Note that running sync tests (tests/sync/) requires the pCloud Drive app to have a sync set up and the SYNC_FOLDER_LOCAL_PATH and SYNC_FOLDER_REMOTE_PATH to be configured.

Running Specific Tests

# One test file
pytest tests/drive/test_basic.py

# Drive tests only
pytest tests/drive/

# Sync Folder tests only
pytest tests/sync/

# One specific test
pytest tests/drive/test_basic.py::TestBasic::test_create_file_syncs_to_cloud

# With verbose output
pytest -v

Useful Options

# Stop on first failure
pytest -x

# Show local variables on failure
pytest -l

# Rerun only failed tests from last run
pytest --lf

# Run last failed test first, then all
pytest --ff

# Show what tests will run (without running them)
pytest --collect-only

# Generate HTML report
pytest --html=report.html --self-contained-html

How Tests Work

Basic Workflow:

1. Setup: Each test creates a unique subfolder in the test folder
2. Action: Test creates/modifies/deletes files on the virtual drive or sync folder
3. Wait: Waits for files to sync (polling with timeout)
4. Verify: Verifies through pCloud API that changes have synced
5. Cleanup: Automatic cleanup after test

Example:

def test_create_file_syncs_to_cloud(test_subfolder):
    # 1. Create file on virtual drive
    test_subfolder.create_file('test.txt', content='Hello World')

    # 2. Verify the file appears remotely and that both checksums match
    assert test_subfolder.wait_for_file_sync('test.txt')

Architecture

Helper Classes

The test suite is built around two main helper classes:

1. VirtualDriveHelper

For testing with mounted pCloud Virtual Drive:

2. SyncFolderHelper

For testing with regular sync folder:

Pytest Fixtures

Key fixtures:

• sync_helper - Helper instance provided by per-directory conftest (tests/drive/conftest.py or tests/sync/conftest.py)
• test_subfolder - Isolated subfolder for each test (automatically cleaned up)
• pcloud - Direct pCloud API access

Troubleshooting

"pCloud Drive not mounted"

# Check if drive is mounted
ls ~/pCloud Drive

# Check the correct path in .env or environment
cat .env | grep DRIVE_PATH
echo $DRIVE_PATH

"PCLOUD_AUTH_TOKEN must be provided"

# Check that the token is set in .env or environment
cat .env | grep PCLOUD_AUTH_TOKEN
echo $PCLOUD_AUTH_TOKEN

"File did not sync within timeout"

• Increase SYNC_TIMEOUT in .env or environment (default is 120 seconds)
• Check internet connection
• Check that pCloud Drive app is running properly
• For large files, consider increasing the timeout

Tests failed but files are not cleaned up

Set CLEAN_TEST_FOLDER=true in your .env or environment to automatically delete and recreate the test folder at the start of the next run. Alternatively, clean up manually:

# Manually delete test folder
rm -rf ~/pCloud\ Drive/test-sync-automation

# Or via pCloud web interface

Best Practices

1. Always run tests with mounted drive (for Virtual Drive mode)
2. Don't modify test folder manually while tests are running
3. Use checksums for data integrity verification
4. Allow sufficient timeout for large files
5. Cleanup is automatic but you can check test folder manually if needed
6. Run tests in both directories (tests/drive/ and tests/sync/) for comprehensive coverage
7. Use appropriate test markers to organize tests

Known Limitations

• Sync time depends on file size and internet speed
• pCloud API has rate limits - avoid excessive parallel requests
• Some OS may have limitations on file names
• GB-sized file tests are disabled by default (use SKIP_GB_TESTS=false to enable)

Development Guidelines

Adding New Tests

If you find a bug or want to add a test:

1. Create new test in appropriate file under tests/ or tests/drive/ or tests/sync/
2. Use test_subfolder fixture for isolation
3. Follow naming convention: test_descriptive_name
4. Each test should be self-contained and cleanup automatically
5. Always verify sync with checksums

Example test structure:

def test_my_new_feature(test_subfolder):
    """Test description"""
    # Create test file
    test_subfolder.create_file('test.txt', content='content')

    # Wait for sync
    assert test_subfolder.wait_for_file_sync('test.txt')