Testing Quick Reference

Last updated: 2026-03-22

One-page reference for running tests in Filament Address Pro.

Quick Commands

# Run everything (5 min)
php artisan test

# Fast feedback loop (< 5s)
php artisan test --testsuite=Unit --testsuite=Integration

# Before commit (< 15s)
php artisan test --exclude-group=api,pre-release

# Quick health check (< 10s)
php artisan test --group=smoke,performance

# Before release
php artisan test --group=pre-release

---

Test Suites

Suite	Tests	Speed	Command
Unit	252	~0.14s	php artisan test --testsuite=Unit
Integration	868 (4 skipped)	~3-5s	php artisan test --testsuite=Integration
Feature	72	Variable	php artisan test --testsuite=Feature
Smoke	73 (6 skipped)	~7.5s	php artisan test --testsuite=Smoke
Performance	37 (2 skipped)	~0.74s	php artisan test --testsuite=Performance
Total	1,302 passed, 12 skipped	~4.5 min	php artisan test

---

Test Groups

# Smoke tests (quick health checks)
php artisan test --group=smoke

# Performance benchmarks
php artisan test --group=performance

# Pre-release validation (256 countries)
php artisan test --group=pre-release

# International address tests
php artisan test --group=international

# Exclude API tests (for CI)
php artisan test --exclude-group=api

---

Smoke Test Categories

# All smoke tests
php artisan test --group=smoke

# Specific categories
php artisan test --group=smoke-api           # External API tests only
php artisan test --group=smoke-components    # Component instantiation only

# Exclude API tests (for CI)
php artisan test --group=smoke --exclude-group=smoke-api

---

Performance Test Categories

# All performance tests
php artisan test --group=performance

# All performance tests (no sub-groups defined)
php artisan test --testsuite=Performance

---

Running Specific Tests

# By file
php artisan test packages/filament-address-pro/tests/Unit/Extractors/JapaneseAddressExtractorTest.php

# By name pattern
php artisan test --filter="japanese extractor"

# By multiple filters
php artisan test --filter="geocoding|subdivision"

---

Development Workflows

During Development (Fast Feedback)

# Run after each change (< 5s)
php artisan test --testsuite=Unit --testsuite=Integration

Before Git Commit

# Comprehensive but fast (< 15s)
php artisan test --exclude-group=api,pre-release

Before Git Push

# Health check + performance (< 10s)
php artisan test --group=smoke,performance

Before Pull Request

# Full suite (< 5 min)
php artisan test

Before Release

# Full validation
php artisan test
php artisan test --group=pre-release

---

CI/CD Workflows

Pull Request

php artisan test --testsuite=Unit
php artisan test --testsuite=Integration
php artisan test --group=smoke --exclude-group=smoke-api

Nightly Build

php artisan test
php artisan test --group=performance

Pre-Release

php artisan test
php artisan test --group=pre-release

---

Test Database Setup

One-Time Setup

# Create database
mysql -u root -e "CREATE DATABASE filament_addresses_test;"

# Run migrations
DB_DATABASE=filament_addresses_test php artisan migrate --force \
  --path="packages/filament-address-pro/database/migrations"

# Seed data
DB_DATABASE=filament_addresses_test php artisan db:seed \
  --class="Viewflex\FilamentAddress\Database\Seeders\CountriesDomainSeeder"

Reset Database

DB_DATABASE=filament_addresses_test php artisan migrate:fresh --force
DB_DATABASE=filament_addresses_test php artisan migrate --force \
  --path="packages/filament-address-pro/database/migrations"
DB_DATABASE=filament_addresses_test php artisan db:seed \
  --class="Viewflex\FilamentAddress\Database\Seeders\CountriesDomainSeeder"

---

Coverage Summary

Category	Count	What It Tests
Pure Unit	112	Business logic, no dependencies
Integration	868 (4 skipped)	Laravel + Database (includes pre-release validation)
Feature	72	Full-stack + APIs
Smoke	73 (6 skipped)	Health checks
Performance	37 (2 skipped)	Timing benchmarks
TOTAL	1,302 passed, 12 skipped	60,000+ assertions

---

Troubleshooting

Tests Fail with "Class not found"

composer dump-autoload

Database Tests Fail

DB_DATABASE=filament_addresses_test php artisan migrate:fresh --force
DB_DATABASE=filament_addresses_test php artisan migrate --force \
  --path="packages/filament-address-pro/database/migrations"
DB_DATABASE=filament_addresses_test php artisan db:seed \
  --class="Viewflex\FilamentAddress\Database\Seeders\CountriesDomainSeeder"

Memory Limit

php -d memory_limit=512M artisan test

Too Slow

# Run only fast tests
php artisan test --testsuite=Unit --testsuite=Integration

---

Performance Baselines

All operations should meet these baselines:

Operation	Baseline
Service instantiation	< 1ms
Subdivision retrieval	< 2ms
Extractor execution	< 0.2ms
Cache key generation	< 0.01ms
Fixture parsing	< 0.5ms

Run performance tests to verify: php artisan test --group=performance

---

Test Groups Reference

Group	Purpose	Speed	Use When
smoke	Health checks	~7.5s	Daily, after setup
smoke-api	API connectivity	Variable	Manual only
performance	Benchmarks	~0.7s	Before release
pre-release	All countries	~2min	Before release
international	46 countries	~0.5s	After changes
api	External APIs	Variable	Manual only

---

Documentation

• Full Testing Guide: TESTING.md
• Smoke Tests: tests/Smoke/README.md
• Performance Tests: tests/Performance/README.md

---

Test Architecture

           Feature Tests (52)
              Full Stack
                  ↑
     Integration Tests (521)
        Laravel + Database
                  ↑
       Pure Unit Tests (112)
         Business Logic

    Smoke Tests (71)     Performance Tests (37)
   Quick Validation      Timing Benchmarks

Test Pyramid: More unit tests, fewer feature tests Smoke Tests: Horizontal health checks across all layers Performance Tests: Continuous benchmarking

---

Key Principles

1. Fast Feedback: Unit + Integration = < 5s
2. Test Behavior: Not implementation details
3. Smoke Tests: Run daily for health
4. Performance: Catch regressions early
5. Pre-Release: Validate all 256 countries

---

Support

For detailed documentation: docs/TESTING.md

For questions or issues: See package documentation