Skip to content

Running local Tests in Cypht

Jump to bottom Edit New page
Alfred Syatsukwa edited this page Nov 20, 2025 · 1 revision

Running local Tests in Cypht

Related issue: https://github.com/cypht-org/cypht/issues/1011

This guide covers how to set up and run PHPUnit tests for the Cypht webmail application.

Table of Contents

Quick Start

# 1. Create test environment configuration
cp .env.test.example .env.test

# 2. Edit .env.test with your database credentials
nano .env.test

# 3. Setup database structure
php scripts/setup_database.php --env=.env.test

# 4. Seed test data (required!)
mysql -u YOUR_USER -pYOUR_PASS YOUR_DB < tests/phpunit/data/seed_mysql.sql

# 5. Run all tests
vendor/bin/phpunit --config=tests/phpunit/phpunit.xml

Requirements

System Requirements

  • PHP 8.1 or higher
  • Composer
  • One of the following databases:
    • MySQL 5.7+ / MariaDB 10.3+
    • PostgreSQL 12+
    • SQLite 3.8+

PHP Extensions Required

  • pdo
  • pdo_mysql (for MySQL)
  • pdo_pgsql (for PostgreSQL)
  • pdo_sqlite (for SQLite)
  • sodium
  • mbstring
  • xdebug (for test coverage)

Note: This guide assumes you have already run composer install to install Cypht dependencies (including PHPUnit).

Database Setup

Configuration File

All test database configuration is managed through the .env.test file:

cp .env.test.example .env.test

The .env.test file is gitignored, so your local credentials are safe.

MySQL/MariaDB

1. Create Database and User

mysql -u root -p
CREATE DATABASE cypht_test;
CREATE USER 'cypht_test'@'localhost' IDENTIFIED BY 'cypht_test';
GRANT ALL PRIVILEGES ON cypht_test.* TO 'cypht_test'@'localhost';
FLUSH PRIVILEGES;
EXIT;

2. Configure .env.test

DB_DRIVER=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=cypht_test
DB_USER=cypht_test
DB_PASS=cypht_test
DB_CONNECTION_TYPE=host

3. Setup Database Structure

php scripts/setup_database.php --env=.env.test

4. Seed Test Data

mysql -u cypht_test -pcypht_test cypht_test < tests/phpunit/data/seed_mysql.sql

Note: No space between -p and the password!

Using Non-Standard Port

If your MySQL runs on a different port (e.g., 3307):

DB_HOST=127.0.0.1:3307

PostgreSQL

1. Create Database and User

sudo -u postgres psql
CREATE DATABASE cypht_test;
CREATE USER cypht_test WITH PASSWORD 'cypht_test';
GRANT ALL PRIVILEGES ON DATABASE cypht_test TO cypht_test;
\q

2. Configure .env.test

DB_DRIVER=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_NAME=cypht_test
DB_USER=cypht_test
DB_PASS=cypht_test
DB_CONNECTION_TYPE=host

3. Setup Database Structure

php scripts/setup_database.php --env=.env.test

4. Seed Test Data

Using password authentication:

PGPASSWORD=cypht_test psql -h localhost -U cypht_test -d cypht_test < tests/phpunit/data/seed_pgsql.sql

Or using sudo (peer authentication):

sudo -u postgres psql -d cypht_test < tests/phpunit/data/seed_pgsql.sql

SQLite

1. Configure .env.test

DB_DRIVER=sqlite
DB_CONNECTION_TYPE=socket
DB_SOCKET=/tmp/cypht_test.db

2. Setup Database Structure

php scripts/setup_database.php --env=.env.test

3. Seed Test Data

sqlite3 /tmp/cypht_test.db < tests/phpunit/data/seed_sqlite.sql

Running Tests

Run All Tests

vendor/bin/phpunit --config=tests/phpunit/phpunit.xml

Or using the full path:

php vendor/phpunit/phpunit/phpunit --configuration tests/phpunit/phpunit.xml

Run Specific Test Suite

# Run only session tests
vendor/bin/phpunit --config=tests/phpunit/phpunit.xml --testsuite=session

# Run only database tests
vendor/bin/phpunit --config=tests/phpunit/phpunit.xml --testsuite=db

# Run only cache tests
vendor/bin/phpunit --config=tests/phpunit/phpunit.xml --testsuite=cache

Run Specific Test File

vendor/bin/phpunit tests/phpunit/session.php --config=tests/phpunit/phpunit.xml
vendor/bin/phpunit tests/phpunit/db.php --config=tests/phpunit/phpunit.xml

Run Specific Test Method

vendor/bin/phpunit --config=tests/phpunit/phpunit.xml --filter=test_check

Run with Test Documentation

vendor/bin/phpunit --config=tests/phpunit/phpunit.xml --testdox

Generate Code Coverage Report

export XDEBUG_MODE=coverage
vendor/bin/phpunit --config=tests/phpunit/phpunit.xml --coverage-html build/coverage

Then open build/coverage/index.html in your browser.

Troubleshooting

Tests Fail on First Run

Problem: Tests fail with errors about missing users or authentication failures.

Solution: Make sure you seeded the test data:

# For MySQL
mysql -u cypht_test -pcypht_test cypht_test < tests/phpunit/data/seed_mysql.sql

# For PostgreSQL
sudo -u postgres psql -d cypht_test < tests/phpunit/data/seed_pgsql.sql

# For SQLite
sqlite3 /tmp/cypht_test.db < tests/phpunit/data/seed_sqlite.sql

Database Connection Errors

Problem: Unable to connect to database

Solutions:

  1. Verify database is running:

    # MySQL
systemctl status mysql

# PostgreSQL
systemctl status postgresql

  2. Check credentials in .env.test:

    cat .env.test

  3. Test connection manually:

    # MySQL
mysql -u cypht_test -pcypht_test cypht_test -e "SELECT 1;"

# PostgreSQL
psql -h localhost -U cypht_test -d cypht_test -c "SELECT 1;"

Wrong Database Name in Tests

Problem: Test test_build_dsn fails with database name mismatch.

Solution: This is normal if you changed the database name in .env.test. The test now uses the actual database name from your configuration.

Permission Denied Errors

Problem: Access denied or FATAL: password authentication failed

Solutions:

  1. For MySQL, verify user privileges:

    SHOW GRANTS FOR 'cypht_test'@'localhost';

  2. For PostgreSQL, check pg_hba.conf authentication settings.

  3. Recreate the user with correct permissions (see Database Setup sections above).

PostgreSQL Peer Authentication Failed

Problem: FATAL: Peer authentication failed for user "postgres"

Solution: Use -h localhost to force password authentication:

PGPASSWORD=cypht_test psql -h localhost -U cypht_test -d cypht_test < tests/phpunit/data/seed_pgsql.sql

Or use sudo with peer authentication:

sudo -u postgres psql -d cypht_test < tests/phpunit/data/seed_pgsql.sql

Clear PHPUnit Cache

If tests behave unexpectedly after configuration changes:

rm -rf tests/phpunit/.phpunit.cache

Custom Test Data

The seed files are located in tests/phpunit/data/:

  • seed_mysql.sql - MySQL/MariaDB seed data
  • seed_pgsql.sql - PostgreSQL seed data
  • seed_sqlite.sql - SQLite seed data

Test Users Included:

  • unittestuser / unittestpass - Used for authentication tests
  • testuser - Used for configuration tests

If you need to modify test data, edit the appropriate seed file and re-seed:

mysql -u cypht_test -pcypht_test cypht_test < tests/phpunit/data/seed_mysql.sql

Available Test Suites

Run vendor/bin/phpunit --list-suites --config=tests/phpunit/phpunit.xml to see all available test suites, including:

  • session - Session management tests
  • db - Database connection and query tests
  • cache - Cache implementation tests
  • config - Configuration handling tests
  • auth - Authentication tests
  • module - Module system tests
  • And many more...

Test Data Reference

Database Schema

The test database schema is automatically created by setup_database.php from:

  • database/mysql_schema.sql (for MySQL)
  • database/pgsql_schema.sql (for PostgreSQL)
  • database/sqlite_schema.sql (for SQLite)

Required Test Users

Username Password Purpose Hash Type
unittestuser unittestpass Authentication & session tests SHA512 with salt
testuser (hashed) Configuration & settings tests Argon2id

Important: These users MUST exist for tests to pass. They are created by running the seed SQL files.

Getting Help

If you encounter issues:

  1. Check this documentation
  2. Verify your .env.test configuration
  3. Ensure test data is seeded
  4. Check the GitHub Issues
  5. Join our Community Chat

Contributing

When adding new tests that require database setup:

  1. Document any new test users needed
  2. Update the seed files for all database types
  3. Update this documentation
  4. Ensure tests work on fresh database setup

###

>

Clone this wiki locally