# GitConverter.TestsApp

Comprehensive test project containing unit, integration and acceptance tests for the GitConverter solution. This README documents what is tested, project structure, how to run and debug tests locally, CI guidance, and how to add new tests or sample data.

Table of contents
- Purpose
- What is tested
- Project structure
- How to run tests
- Test conventions and patterns
- Test data and samples
- Integration gating and licensing
- Debugging & diagnostics
- Adding tests and samples
- CI guidance
- Troubleshooting
- Contact

## Purpose

This project validates correctness and resilience of the conversion tooling including:
- Format detection and routing (which converter to use for given inputs)
- File/archive handling and safe extraction logic (zip-slip protection)
- End-to-end conversions for representative small sample artifacts
- Command-line parsing and `Program.Run` behavior for the ConsoleApp

## What is tested

- Unit tests
  - Detection heuristics (`FactoryHelpers`, `JsonFormatDetector`), routing (`ConverterFactory`), and `ConverterUtils` helpers.
  - Fast, deterministic tests that do not require heavy dependencies.

- Integration tests
  - End-to-end converter flows (CSV, Shapefile, GML and other supported formats) using small on-disk sample artifacts.
  - CLI/Program tests that invoke `Program.Run(string[])` via reflection to validate parsing and behavior without terminating the test process.

- Logging & diagnostics
  - Tests that assert logging messages are emitted at expected levels (Debug/Info/Warn/Error). Use `TestLogger` and `LogAssert` helpers.

## Project structure

- `Converters` — converter-focused unit and integration tests.
- `Factories` — unit tests for `ConverterFactory`, `FactoryHelpers` and input-detection helpers.
- `Helpers` / `TestSupport` — shared helpers and constants (`IntegrationTestConstants`, `TestLogger`, `LogAssert`).
- `TestData` — sample artifacts used by integration tests (kept small and optionally not committed).
- `Licensing` — guidance and helpers around Aspose license application (licensed tests are gated).
- `Models` — tests and helpers around `ConversionResult`, `FileExtensionHelpers` and related model types.

## How to run tests

- IDE (Visual Studio / Rider)
  - Build solution and run tests via Test Explorer.
  - Ensure the ConsoleApp project is built when running CLI/Program tests because tests probe ConsoleApp build outputs.

- dotnet CLI
  - From repository root:
    ```bash
    dotnet build
    dotnet test ./GitConverter.TestsApp/GitConverter.TestsApp.csproj
    ```

- Run a single test
  - Use the test runner or `dotnet test --filter "FullyQualifiedName~TestName"`.

## Test conventions and patterns

- Unique temp roots
  - Create a unique temporary root per test: `Path.GetTempPath()` + GUID; delete it in `Dispose()` (best-effort) to avoid interference.

- Non-destructive assertions
  - Integration tests assert presence of output files (one or more) rather than exact file names. Use `FileExtensionHelpers` to compute expected extensions.

- API usage
  - Prefer `IConverterFactory.TryCreate(...)` in CLI-like and test flows; use `Create(...)` when asserting suggestion behavior and exceptions.

- Logging assertions
  - Capture logs with `TestLogger` and assert using `LogAssert.ContainsMessage(logger, level, token)` (case-insensitive substring checks are recommended).

## Test data and samples

- Location: `TestData/<format>` (for example `TestData/Shapefile`).
- csproj: mark samples with `<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>` so they are available at runtime.
- Keep samples small (KB–MB) and avoid committing proprietary datasets. Integration tests must check for sample presence and skip when absent.

## Integration gating and licensing

- Gate heavier or licensed integration tests behind an opt-in environment variable to keep main CI fast and public-friendly:
  - `GITCONVERTER_ENABLE_INTEGRATION=1` — run gated integration tests.
  - `GITCONVERTER_ASPOSE_LICENSE_PATH` — optional file path to an Aspose license for licensed runs.

- License guidance
  - Do NOT commit license files to source control. Provision licenses via secure CI secrets when running licensed integration pipelines.
  - Tests that require a license should check `AsposeLicenseManager.ApplyLicense()` (or the environment variable) and skip when licensing is unavailable.

## Debugging & diagnostics

- Console capture
  - CLI tests capture `Console.Out` and `Console.Error` using `StringWriter`. Combine both streams when diagnosing failures.

- Reflection probe diagnostics
  - When `Program` cannot be found the helper prints probed locations. Inspect those paths to ensure ConsoleApp build outputs exist.

- Log capture
  - Use `TestLogger` to capture `Debug/Info/Warn/Error` output. When investigating failures include captured logs in issues.

## Adding tests and samples

- Unit tests
  - Add deterministic unit tests under the appropriate folder. Use fakes to avoid heavy dependencies on Aspose or other drivers.

- Integration tests
  1. Add small sample artifacts under `TestData/<format>` and set `CopyToOutputDirectory=PreserveNewest`.
  2. Use `IntegrationTestConstants` to locate samples in tests.
  3. Create unique temp `output` and `temp` folders and clean them up in `Dispose()`.
  4. Assert presence of output files or appropriate `ConversionResult.Failure` messages.

## CI guidance

- Keep most tests unlicensed and fast for main CI.
- Run licensed/integration scenarios in separate pipelines or matrix jobs that provision secrets and samples.
- Mark long-running or flaky tests so CI can opt-out when needed.

## Troubleshooting checklist

- Missing `Program` type in CLI tests: ensure ConsoleApp is built and its assembly is present in probed output directories.
- Missing sample files: verify `CopyToOutputDirectory` is set and files exist in test output.
- Failing logging assertions: dump `TestLogger` messages and assert on stable tokens rather than exact messages.

## Contact

- File an issue including: failing test name and stack trace, captured stdout/stderr, `TestLogger` output and sample file paths if relevant.

This document is the canonical reference for contributors adding and maintaining tests in `GitConverter.TestsApp`. Update README entries when adding new test data sets, gating flags, or helper APIs.