# Converters test guidance — GitConverter.Lib.Converters

This folder contains tests and documentation that validate the library-level converter implementations and the helper logic that supports them. The guidance below is intended for maintainers adding or debugging tests for converters, detection heuristics, and archive handling.

Contents
- `UniversalGisConverter` and other converter unit/integration tests
- Detection tests for JSON variants and archive voting
- Utility tests for `ConverterUtils` (validation, archive listing, zip-slip protection)
- Helpers and test doubles used to avoid invoking heavy conversion engines in unit tests

Goals
- Verify correct detection and routing of inputs to converters (extension maps, archive heuristics, JSON fingerprints).
- Ensure converters perform safe extraction, correct option construction and report `ConversionResult` consistently.
- Provide small integration tests exercising end-to-end behavior using tiny sample artifacts while remaining CI-friendly.

Test categories

1. Unit tests
   - Fast, deterministic tests that validate detection heuristics, factory routing, and `ConverterUtils` behavior. Use fakes for `IConverter` where appropriate.
   - Examples: `FactoryHelpersTests`, `ConverterFactoryInputExtensionsTests`, `ConverterFactoryTests`.

2. Integration tests
   - End-to-end converter invocations that may exercise Aspose.GIS-backed conversions. Keep these tests small and gate them when a license or large sample files are required.
   - Examples: `UniversalGisConverterTests` (contains both early-failure unit tests and gated integration scenarios).

3. Logging and diagnostic tests
   - Validate the library emits expected tokens at appropriate levels (Debug/Info/Warn/Error) through the `IAppLogger` abstraction. Use `TestLogger` and `LogAssert` helpers to capture and assert logs.

Helpers and patterns

- Test doubles and factory injection
  - For unit tests inject a small `Dictionary<string, Func<IConverter>>` into `ConverterFactory` so tests can verify routing without invoking heavy converters.
  - Use a `FakeFactory` that records `LastRequestedKey` to assert which converter the detection code attempted to create.

- Temporary directories
  - Create a unique temp root per test using `Path.GetTempPath()` + GUID and remove it in `Dispose()` (best-effort). This prevents cross-test interference when running tests in parallel.

- Archive handling tests
  - Use `ZipArchive` or `ZipFile.CreateFromDirectory` to create small zips that represent archives under test. Test vote-based classification for multiple JSON entries and missing companion files for multi-file formats (e.g., shapefile components).

- Integration gating
  - Gate heavy or licensed integration tests behind environment variables such as `GITCONVERTER_ENABLE_INTEGRATION` and/or license checks (e.g., `AsposeLicenseManager.ApplyLicense()` success). This keeps CI green for contributors without private samples or licenses.

Key logs and tokens to assert

- Parameter trace (Debug): `CsvConverter.Convert params:` — contains incoming arguments for diagnostic purposes (note historical naming; content is accurate).
- Conversion start (Info): `starting conversion (option='...')`.
- Conversion success (Info): `Conversion succeeded: <path>`.
- Conversion failure (Error/Info): `Conversion failed: <message>`.
- Cleanup lifecycle (Debug/Info/Warn): `Cleaning up temp folder.`, `Temp folder '<path>' deleted.`, `Cleanup failed:`.

Typical tests to add when adding a new converter

1. Detection tests
   - Add unit tests to `ConverterFactoryInputExtensionsTests` that exercise single-file JSON detection and archive voting (including tie-breakers).

2. Converter unit tests
   - Add unit tests that exercise `UniversalGisConverter` early failure paths (invalid inputs, missing archive components, invalid options mapping).

3. Integration test (optional)
   - Add a small sample to `TestsApp/TestData/<format>` and a gated integration test that performs a conversion and asserts output filename extension(s) exist in the `output` folder.

CI guidance

- Keep unit tests fast and free of external dependencies.
- Integration tests that require private sample data or vendor licenses should be optional for the main CI pipeline. Use separate pipelines or matrix jobs to run licensed integration scenarios.
- Ensure any provisioning of license files in CI uses secure storage (pipeline secrets) and does not commit licenses to the repository.

Troubleshooting checklist

- Tests failing with "no Program type found"
  - Ensure `GitConverter.ConsoleApp` is built and that test build outputs contain the ConsoleApp assembly. The reflection probe prints probed locations — inspect those paths.

- Tests failing with unexpected error messages
  - Tests should use tolerant message checks (case-insensitive substring checks) for log and result message assertions. If an implementation change causes many failures update tests to assert on stable tokens.

- Archive extraction failures
  - Ensure test-created zips include the expected entry paths (include base directory when zipping a folder containing a `.gdb` if you want the `.gdb` folder visible in entry names).

- License-related test skips
  - For tests that require Aspose licensing ensure `AsposeLicenseManager.ApplyLicense()` is used or the test checks `GITCONVERTER_ASPOSE_LICENSE_PATH` in CI and skips when not provided.

Contact

- When filing issues about failing converter tests include:
  - The failing test name and stack trace
  - Captured stdout/stderr and `TestLogger` output for the run
  - Any sample artifact used by the test (or its expected location under `TestData`)

This README is intended as the canonical reference for maintainers working in the converters test area. For per-test helper details see XML remarks in the test helper classes and the test source files themselves.