Testing Quick Reference

Last updated: 2026-10-12

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

Prerequisites

Tests run from the package directory, not from your Laravel app. Install dev dependencies first:

bash

cd vendor/viewflex/filament-address-pro
composer install

Unit tests work immediately after that. Integration/Feature/Smoke/Performance tests also require a pre-seeded MySQL database:

bash

cp phpunit.xml.dist phpunit.xml          # then set DB_HOST/PORT/USER/PASS
mysql -u root -e "CREATE DATABASE filament_addresses_test;"
vendor/bin/testbench migrate --force
vendor/bin/testbench db:seed --force \
  --class="Viewflex\FilamentAddress\Database\Seeders\CountriesDomainSeeder"

See TESTING.md for full setup detail.

Quick Commands

bash

# Run everything (5 min)
composer test

# Fast feedback loop (< 5s)
vendor/bin/pest --testsuite=Unit --testsuite=Integration

# Before commit (< 15s)
vendor/bin/pest --exclude-group=api,pre-release

# Quick health check (< 10s)
vendor/bin/pest --group=smoke,performance

# Before release
vendor/bin/pest --group=pre-release

Test Suites

Suite	Tests	Speed	Command
Unit	252	~0.14s	`vendor/bin/pest --testsuite=Unit`
Integration	868 (4 skipped)	~3-5s	`vendor/bin/pest --testsuite=Integration`
Feature	72	Variable	`vendor/bin/pest --testsuite=Feature`
Smoke	73 (6 skipped)	~7.5s	`vendor/bin/pest --testsuite=Smoke`
Performance	37 (2 skipped)	~0.74s	`vendor/bin/pest --testsuite=Performance`
Total	1,308 passed, 12 skipped	~4.5 min	`composer test`

Test Groups

bash

# Smoke tests (quick health checks)
vendor/bin/pest --group=smoke

# Performance benchmarks
vendor/bin/pest --group=performance

# Pre-release validation (256 countries)
vendor/bin/pest --group=pre-release

# International address tests
vendor/bin/pest --group=international

# Exclude API tests (for CI)
vendor/bin/pest --exclude-group=api

Smoke Test Categories

bash

# All smoke tests
vendor/bin/pest --group=smoke

# Specific categories
vendor/bin/pest --group=smoke-api           # External API tests only
vendor/bin/pest --group=smoke-components    # Component instantiation only

# Exclude API tests (for CI)
vendor/bin/pest --group=smoke --exclude-group=smoke-api

Performance Test Categories

bash

# All performance tests
vendor/bin/pest --group=performance

# All performance tests (no sub-groups defined)
vendor/bin/pest --testsuite=Performance

Running Specific Tests

bash

# By file
vendor/bin/pest tests/Unit/Extractors/JapaneseAddressExtractorTest.php

# By name pattern
vendor/bin/pest --filter="japanese extractor"

# By multiple filters
vendor/bin/pest --filter="geocoding|subdivision"

Development Workflows

During Development (Fast Feedback)

bash

# Run after each change (< 5s)
vendor/bin/pest --testsuite=Unit --testsuite=Integration

Before Git Commit

bash

# Comprehensive but fast (< 15s)
vendor/bin/pest --exclude-group=api,pre-release

Before Git Push

bash

# Health check + performance (< 10s)
vendor/bin/pest --group=smoke,performance

Before Pull Request

bash

# Full suite (< 5 min)
composer test

Before Release

bash

# Full validation
composer test
vendor/bin/pest --group=pre-release

CI/CD Workflows

Pull Request

bash

vendor/bin/pest --testsuite=Unit
vendor/bin/pest --testsuite=Integration
vendor/bin/pest --group=smoke --exclude-group=smoke-api

Nightly Build

bash

composer test
vendor/bin/pest --group=performance

Pre-Release

bash

composer test
vendor/bin/pest --group=pre-release

Test Database Setup

One-Time Setup

bash

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

# Run migrations
vendor/bin/testbench migrate --force

# Seed data
vendor/bin/testbench db:seed --force \
  --class="Viewflex\FilamentAddress\Database\Seeders\CountriesDomainSeeder"

Reset Database

bash

vendor/bin/testbench migrate:fresh --force
vendor/bin/testbench migrate --force
vendor/bin/testbench db:seed --force \
  --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,308 passed, 12 skipped	60,000+ assertions

Troubleshooting

Tests Fail with "Class not found"

bash

composer dump-autoload

Database Tests Fail

bash

vendor/bin/testbench migrate:fresh --force
vendor/bin/testbench migrate --force
vendor/bin/testbench db:seed --force \
  --class="Viewflex\FilamentAddress\Database\Seeders\CountriesDomainSeeder"

Memory Limit

bash

php -d memory_limit=512M vendor/bin/pest

Too Slow

bash

# Run only fast tests
vendor/bin/pest --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: vendor/bin/pest --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

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

Support

For detailed documentation: docs/TESTING.md

For questions or issues: See package documentation

Testing Quick Reference ​

Prerequisites ​

Quick Commands ​

Test Suites ​

Test Groups ​

Smoke Test Categories ​

Performance Test Categories ​

Running Specific Tests ​

Development Workflows ​

During Development (Fast Feedback) ​

Before Git Commit ​

Before Git Push ​

Before Pull Request ​

Before Release ​

CI/CD Workflows ​

Pull Request ​

Nightly Build ​

Pre-Release ​

Test Database Setup ​

One-Time Setup ​

Reset Database ​

Coverage Summary ​

Troubleshooting ​

Tests Fail with "Class not found" ​

Database Tests Fail ​

Memory Limit ​

Too Slow ​

Performance Baselines ​

Test Groups Reference ​

Documentation ​

Test Architecture ​

Key Principles ​

Support ​

Testing Quick Reference

Prerequisites

Quick Commands

Test Suites

Test Groups

Smoke Test Categories

Performance Test Categories

Running Specific Tests

Development Workflows

During Development (Fast Feedback)

Before Git Commit

Before Git Push

Before Pull Request

Before Release

CI/CD Workflows

Pull Request

Nightly Build

Pre-Release

Test Database Setup

One-Time Setup

Reset Database

Coverage Summary

Troubleshooting

Tests Fail with "Class not found"

Database Tests Fail

Memory Limit

Too Slow

Performance Baselines

Test Groups Reference

Documentation

Test Architecture

Key Principles

Support