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
• Requirements
• Database Setup
  • MySQL/MariaDB
  • PostgreSQL
  • SQLite
• Running Tests
• Troubleshooting

---

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