|
| 1 | +# Testing Guide |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +The GEDCOM X PHP SDK includes a comprehensive test suite using PHPUnit 9.5+ to ensure compatibility across PHP versions 7.4 through 8.3. |
| 6 | + |
| 7 | +## Running Tests |
| 8 | + |
| 9 | +### Prerequisites |
| 10 | + |
| 11 | +- PHP 7.4, 8.0, 8.1, 8.2, or 8.3 |
| 12 | +- Composer dependencies installed |
| 13 | +- Xdebug or PCOV extension (optional, for coverage reports) |
| 14 | + |
| 15 | +### Basic Test Execution |
| 16 | + |
| 17 | +Run the complete test suite: |
| 18 | + |
| 19 | +```bash |
| 20 | +vendor/bin/phpunit |
| 21 | +``` |
| 22 | + |
| 23 | +### Running Specific Tests |
| 24 | + |
| 25 | +Run a specific test file: |
| 26 | + |
| 27 | +```bash |
| 28 | +vendor/bin/phpunit tests/unit/PersonTests.php |
| 29 | +``` |
| 30 | + |
| 31 | +Run a specific test method: |
| 32 | + |
| 33 | +```bash |
| 34 | +vendor/bin/phpunit --filter testPerson |
| 35 | +``` |
| 36 | + |
| 37 | +## Code Coverage |
| 38 | + |
| 39 | +### Generating Coverage Reports |
| 40 | + |
| 41 | +**HTML Report** (most detailed): |
| 42 | + |
| 43 | +```bash |
| 44 | +vendor/bin/phpunit --coverage-html build/coverage |
| 45 | +``` |
| 46 | + |
| 47 | +Then open `build/coverage/index.html` in your browser. |
| 48 | + |
| 49 | +**Text Report** (terminal output): |
| 50 | + |
| 51 | +```bash |
| 52 | +vendor/bin/phpunit --coverage-text |
| 53 | +``` |
| 54 | + |
| 55 | +**Clover XML** (for CI/CD integration): |
| 56 | + |
| 57 | +```bash |
| 58 | +vendor/bin/phpunit --coverage-clover build/logs/clover.xml |
| 59 | +``` |
| 60 | + |
| 61 | +### Coverage Baseline (2026) |
| 62 | + |
| 63 | +Current test coverage baseline established: |
| 64 | + |
| 65 | +- **Test Files**: 28 test suites |
| 66 | +- **Test Cases**: 99 tests with 237 assertions |
| 67 | +- **Source Files**: 125+ PHP files |
| 68 | +- **Core Models**: Complete GEDCOM X conceptual model class coverage |
| 69 | +- **Extensions**: Comprehensive FamilySearch platform extension coverage |
| 70 | + |
| 71 | +### Coverage Areas |
| 72 | + |
| 73 | +#### Well-Covered Components (as of v3.2.0) |
| 74 | + |
| 75 | +- **GEDCOM X file format**: .gedx reading and writing, XML serialization/deserialization |
| 76 | +- **Core conclusion models**: Person, Gender, Fact, Name, NameForm, NamePart, Event, EventRole, Relationship, Document, PlaceDescription, PlaceReference, DateInfo, Identifier |
| 77 | +- **Agent models**: Agent, Address, OnlineAccount |
| 78 | +- **Source models**: SourceDescription, SourceReference, SourceCitation, Coverage, CitationField |
| 79 | +- **FamilySearch extensions**: User, Discussion, Comment, DiscussionReference, ChildAndParentsRelationship, ChangeInfo, MatchInfo, Merge, MergeAnalysis, MergeConflict, ArtifactMetadata |
| 80 | + |
| 81 | +#### Areas for Future Expansion |
| 82 | + |
| 83 | +Additional test coverage could be added for: |
| 84 | + |
| 85 | +1. **Abstract/Base Classes** |
| 86 | + - Subject and Conclusion base classes |
| 87 | + - HasFacts trait |
| 88 | + - DisplayProperties models |
| 89 | + |
| 90 | +2. **Serialization Edge Cases** |
| 91 | + - JSON serialization for all models (currently only XML is comprehensively tested) |
| 92 | + - Malformed data handling |
| 93 | + - Namespace handling for extensions |
| 94 | + - Large file performance |
| 95 | + |
| 96 | +4. **Collections and Utilities** |
| 97 | + - Collection class operations |
| 98 | + - Reference resolvers |
| 99 | + - Model visitor patterns |
| 100 | + |
| 101 | +## Test Structure |
| 102 | + |
| 103 | +### Directory Layout |
| 104 | + |
| 105 | +``` |
| 106 | +tests/ |
| 107 | +├── bootstrap.php # Test initialization |
| 108 | +├── ApiTestCase.php # Base test case class |
| 109 | +├── ArtifactBuilder.php # Test artifact generation |
| 110 | +├── PersonBuilder.php # Test person creation |
| 111 | +├── TestBuilder.php # General test utilities |
| 112 | +├── XMLBuilder.php # XML test utilities |
| 113 | +├── files/ # Test fixtures |
| 114 | +│ ├── person.json |
| 115 | +│ ├── record.xml |
| 116 | +│ ├── sample.gedx |
| 117 | +│ └── cap-relationship-control.xml |
| 118 | +├── tmp/ # Temporary test output |
| 119 | +└── unit/ # Unit tests |
| 120 | + ├── PersonTests.php |
| 121 | + ├── XMLTests.php |
| 122 | + └── GedcomxFileTests.php |
| 123 | +``` |
| 124 | + |
| 125 | +### Test Fixtures |
| 126 | + |
| 127 | +Test fixtures are located in `tests/files/`: |
| 128 | + |
| 129 | +- **Core model fixtures**: person.json, gender.json, fact.json, name.json, date-info.json, identifier.json, name-form.json, name-part.json, event.json, event-role.json, relationship.json, document.json, place-description.json, place-reference.json |
| 130 | +- **Agent fixtures**: agent.json, address.json, online-account.json |
| 131 | +- **Source fixtures**: source-description.json, source-citation.json, coverage.json, citation-field.json |
| 132 | +- **FamilySearch extension fixtures**: user.json, discussion.json, comment.json, change-info.json, match-info.json, merge.json |
| 133 | +- **XML fixtures**: record.xml, cap-relationship-control.xml |
| 134 | +- **Archive files**: sample.gedx |
| 135 | +- **Test images**: test-image.jpg (for GEDX file tests) |
| 136 | + |
| 137 | +### Base Test Class |
| 138 | + |
| 139 | +All tests extend `Gedcomx\Tests\ApiTestCase`, which provides: |
| 140 | + |
| 141 | +- Automatic setup and teardown |
| 142 | +- Temporary directory management |
| 143 | +- Test fixture loading helpers |
| 144 | +- Common test utilities |
| 145 | + |
| 146 | +## PHP Version Compatibility |
| 147 | + |
| 148 | +### Tested Versions |
| 149 | + |
| 150 | +The SDK is automatically tested on: |
| 151 | + |
| 152 | +- PHP 7.4 |
| 153 | +- PHP 8.0 |
| 154 | +- PHP 8.1 |
| 155 | +- PHP 8.2 |
| 156 | +- PHP 8.3 |
| 157 | + |
| 158 | +### Compatibility Notes |
| 159 | + |
| 160 | +**PHP 8.0+ Changes Addressed**: |
| 161 | + |
| 162 | +- ✅ Explicit nullable type declarations (`?Type` instead of implicit null defaults) |
| 163 | +- ✅ Return type declarations for interface implementations (ArrayAccess, Countable, IteratorAggregate) |
| 164 | +- ✅ Modern PHPUnit assertions (removed deprecated `assertEqualXMLStructure`) |
| 165 | + |
| 166 | +**External Dependencies**: |
| 167 | + |
| 168 | +Test fixtures are used instead of runtime image generation, eliminating external dependencies and ensuring consistent test behavior across all PHP versions. |
| 169 | + |
| 170 | +## Continuous Integration |
| 171 | + |
| 172 | +### GitHub Actions Workflow |
| 173 | + |
| 174 | +The CI pipeline (`.github/workflows/ci.yml`) automatically: |
| 175 | + |
| 176 | +1. Tests against all supported PHP versions |
| 177 | +2. Validates composer.json and composer.lock |
| 178 | +3. Runs the complete test suite |
| 179 | +4. Generates code coverage reports |
| 180 | +5. Uploads coverage to Coveralls (PHP 8.3 only) |
| 181 | + |
| 182 | +### Running CI Locally |
| 183 | + |
| 184 | +Simulate CI testing for a specific PHP version using Docker: |
| 185 | + |
| 186 | +```bash |
| 187 | +docker run --rm -v $(pwd):/app -w /app php:8.3-cli bash -c \ |
| 188 | + "apt-get update && apt-get install -y git zip unzip && \ |
| 189 | + php -r \"copy('https://getcomposer.org/installer', 'composer-setup.php');\" && \ |
| 190 | + php composer-setup.php --install-dir=/usr/local/bin --filename=composer && \ |
| 191 | + composer install --prefer-dist --no-progress && \ |
| 192 | + vendor/bin/phpunit" |
| 193 | +``` |
| 194 | + |
| 195 | +## Writing New Tests |
| 196 | + |
| 197 | +### Best Practices |
| 198 | + |
| 199 | +1. **Extend ApiTestCase**: Use the base test case for common functionality |
| 200 | +2. **Use Fixtures**: Place test data files in `tests/files/` |
| 201 | +3. **Clean Up**: Tests automatically clean up `tests/tmp/` after each run |
| 202 | +4. **Assertions**: Use modern PHPUnit assertions |
| 203 | +5. **Naming**: Test files should end with `Tests.php` (e.g., `PersonTests.php`) |
| 204 | +6. **Namespace**: Use `Gedcomx\Tests\Unit` or `Gedcomx\Tests\Integration` |
| 205 | + |
| 206 | +### Example Test |
| 207 | + |
| 208 | +```php |
| 209 | +<?php |
| 210 | + |
| 211 | +namespace Gedcomx\Tests\Unit; |
| 212 | + |
| 213 | +use Gedcomx\Tests\ApiTestCase; |
| 214 | +use Gedcomx\Conclusion\Person; |
| 215 | + |
| 216 | +class PersonTests extends ApiTestCase |
| 217 | +{ |
| 218 | + public function testPersonDeserialization() |
| 219 | + { |
| 220 | + $person = new Person($this->loadJson('person.json')); |
| 221 | + |
| 222 | + $this->assertEquals('PPPJ-MYZ', $person->getId()); |
| 223 | + $this->assertCount(2, $person->getFacts()); |
| 224 | + $this->assertCount(1, $person->getNames()); |
| 225 | + } |
| 226 | +} |
| 227 | +``` |
| 228 | + |
| 229 | +## Troubleshooting |
| 230 | + |
| 231 | +### Coverage Not Generated |
| 232 | + |
| 233 | +If coverage reports aren't generated: |
| 234 | + |
| 235 | +1. Install Xdebug: |
| 236 | + ```bash |
| 237 | + pecl install xdebug |
| 238 | + ``` |
| 239 | + |
| 240 | +2. Or install PCOV (faster): |
| 241 | + ```bash |
| 242 | + pecl install pcov |
| 243 | + ``` |
| 244 | + |
| 245 | +3. Verify installation: |
| 246 | + ```bash |
| 247 | + php -m | grep -i xdebug |
| 248 | + # or |
| 249 | + php -m | grep -i pcov |
| 250 | + ``` |
| 251 | + |
| 252 | +### Tests Failing on PHP 8+ |
| 253 | + |
| 254 | +If you see deprecation warnings or failures on PHP 8+: |
| 255 | + |
| 256 | +1. Ensure you're using PHPUnit 9.5+ (check `composer.json`) |
| 257 | +2. Verify explicit nullable types are used (`?Type` not `Type = null`) |
| 258 | +3. Check that interface implementations have proper return types |
| 259 | + |
| 260 | +### Permission Issues with tests/tmp/ |
| 261 | + |
| 262 | +Ensure the temporary directory is writable: |
| 263 | + |
| 264 | +```bash |
| 265 | +chmod 755 tests/tmp |
| 266 | +``` |
| 267 | + |
| 268 | +## Contributing |
| 269 | + |
| 270 | +When contributing new features: |
| 271 | + |
| 272 | +1. Add unit tests for new functionality |
| 273 | +2. Ensure all tests pass on all supported PHP versions |
| 274 | +3. Maintain or improve code coverage |
| 275 | +4. Follow existing test patterns and structure |
| 276 | +5. Update this document if adding new test categories |
| 277 | + |
| 278 | +## References |
| 279 | + |
| 280 | +- [PHPUnit Documentation](https://phpunit.de/documentation.html) |
| 281 | +- [GEDCOM X Specification](http://www.gedcomx.org) |
| 282 | +- [FamilySearch API Documentation](https://www.familysearch.org/developers/) |
0 commit comments