# Test models & helpers — GitConverter.TestsApp.Models

This document describes model-related helpers and conventions that the test projects use to remain
consistent with `GitConverter.Lib` production behavior. It focuses on small, deterministic helpers
and patterns that make assertions robust across unit and integration tests.

Scope
- Guidance for using library model types in tests (not exhaustive API docs):
  - `ConversionResult` and `ConversionStatus`
  - `FileExtension` and `FileExtensionHelpers`
  - `ConversionOptions` (as used by converters)
- Best-practice patterns for asserting results and deriving expected filenames/extensions.

Principles
- Tests should rely on the library's helpers for canonical values (file extensions, option mappings)
  rather than duplicating logic in the test code. This keeps tests resilient to non-functional
  renames or re-mappings in the production code.
- Tests should prefer asserting meaningful behavioral outcomes (success vs failure, presence of files,
  and stable message substrings) rather than exact string matches that may change.

Key types and usage

- `ConversionResult`
  - Represents the outcome of a conversion operation. Use the factory helpers when creating expected
    results in tests: `ConversionResult.Success(string message)` and `ConversionResult.Failure(string message)`.
  - Typical assertions:
    - `Assert.Equal(ConversionStatus.Success, result.Status);`
    - `Assert.False(string.IsNullOrWhiteSpace(result.Message));`
  - Note: `ConversionResult` may include diagnostic fields (timestamps, internal codes). Tests should
    compare the `Status` and examine the `Message` for relevant substrings; avoid asserting on timestamps.

- `FileExtension` and `FileExtensionHelpers`
  - Use `FileExtensionHelpers.FromOption(string option)` to map a canonical option name to a `FileExtension` value.
  - Use `FileExtensionHelpers.ToDotExtension(FileExtension ext)` to obtain the platform-appropriate dot-prefixed extension
    (for example, `.geojson`, `.shp`). Relying on these helpers keeps tests in sync with production filename conventions.
  - Example:

```csharp
var ext = FileExtensionHelpers.FromOption("GeoJson");
var dot = FileExtensionHelpers.ToDotExtension(ext.Value); // ".geojson"
```

- `ConversionOptions`
  - When tests need to verify that converters receive specific options, construct a `ConversionOptions`
    instance with the expected `SourceDriverOptions` or other settings and assert on the values the test
    helper observes. Prefer to compare individual option properties rather than relying on object identity.

Assertion patterns and examples

- Prefer presence checks for output files (integration tests):

```csharp
// After a successful conversion assert that at least one file with the expected extension exists
var files = Directory.GetFiles(outputFolder, "*" + expectedDotExt, SearchOption.AllDirectories);
Assert.NotEmpty(files);
```

- Assert on `ConversionResult` semantics rather than full messages:

```csharp
Assert.Equal(ConversionStatus.Failure, result.Status);
Assert.Contains("missing components", result.Message, StringComparison.OrdinalIgnoreCase);
```

- When testing suggestion behavior from factories use substring checks on thrown exception messages:

```csharp
var ex = Assert.Throws<KeyNotFoundException>(() => factory.Create("esrijsn"));
Assert.Contains("Did you mean", ex.Message, StringComparison.OrdinalIgnoreCase);
```

Creating expected filenames

- Use `FileExtensionHelpers` to compute expected filename suffixes used by `ConverterUtils.BuildOutputPath`:

```csharp
var maybeExt = FileExtensionHelpers.FromOption("GeoJson");
var extDot = FileExtensionHelpers.ToDotExtension(maybeExt.Value);
// expected output pattern: "output_YYYYmmdd_HHMMSS" + extDot
```

Test doubles and model usage

- For unit tests that assert routing or invocation without performing real conversions, create small fakes that implement
  `IConverter` and return `ConversionResult.Success("ok")` or `Failure(...)` as appropriate.

- When asserting factory lookup or suggestion behavior prefer injecting custom registration maps into `ConverterFactory`
  so tests avoid instantiating heavy converters.

Edge cases and robustness

- When comparing messages, prefer case-insensitive substring assertions rather than exact equality. This prevents brittle
  failures due to wording changes in diagnostic text.

- Avoid inspecting timestamps or other ephemeral data in `ConversionResult`.

- When tests assert on file-system state, always use unique temp roots (see `TestFileHelpers`) so tests do not interfere with
  each other when running in parallel.

Extending these helpers

- Add small helper assertion methods in the test project (for example `AssertHasOutputFile(outputFolder, ext)`) rather than
  copying similar code across tests.

- If you need additional model helpers exposed for tests, add them under `GitConverter.TestsApp` (not production library) so the
  production code surface remains stable.

Contact

- If you change `FileExtensionHelpers`, `ConversionResult` messages or other model behaviors, update tests that depend on those
  behaviors and consider adding migration notes in this README to help other maintainers.