Epic: Test architecture refactor before 1.0

[iriswolf]

Summary

Refactor the test suite before the first stable release so tests describe TeleFlow contracts clearly and can support long-term API compatibility, coverage reporting, and quality gates.

This is a pre-1.0 stabilization task. It should be done while public contracts can still be clarified, renamed, or split without causing stable-version churn.

Current State

• Architecture tests cover many important behaviors, but several files mix unrelated contracts and runtime scenarios.
• Some tests validate framework behavior well, but the suite structure does not yet make contract ownership obvious.
• Coverage reporting and quality gates are tracked separately in Epic: Coverage reporting and quality gates #18.
• Splitting large architecture test files is tracked separately in Split large architecture test files by semantic area #44.

Target State

• Tests are organized by public contract and runtime boundary, not by accidental historical growth.
• Core framework contracts have focused executable specifications.
• Transport, client, generated registration, analyzer, state/storage, callbacks, filters, middleware, and error handling each have clear test ownership.
• Reflection and generated paths have parity tests where both paths support the same scenario.
• Coverage reporting can be enabled without hiding weakly tested areas behind a single aggregate number.

Proposed Work

• Define the target test taxonomy for the repository.
• Split large test files into semantic areas without changing covered behavior.
• Move shared test fixtures/builders into explicit test support locations.
• Identify tests that currently assert implementation trivia and rewrite them around observable contracts.
• Add missing contract tests discovered during the split.
• Prepare the suite for Codecov or equivalent coverage publication.
• Define coverage quality gates that are useful but not performative.

Boundaries

• This issue should not change production runtime behavior by itself.
• This issue should not block alpha.4 unless a test refactor uncovers a real release-blocking defect.
• Coverage infrastructure belongs with Epic: Coverage reporting and quality gates #18, but the test architecture should make Epic: Coverage reporting and quality gates #18 meaningful.
• Large file splitting overlaps with Split large architecture test files by semantic area #44; this epic should guide that work rather than duplicate it.

Acceptance Criteria

• The repository has a documented test taxonomy before 1.0.0.
• Large mixed test files are split or have an approved split plan.
• Contract-critical areas have named test groups that are easy to find and review.
• Reflection/generated parity expectations are represented by tests where relevant.
• Coverage reporting can be introduced with meaningful area-level interpretation.
• Epic: Coverage reporting and quality gates #18 and Split large architecture test files by semantic area #44 can be completed without guessing how the test suite should be organized.

Related Work

• Epic: Coverage reporting and quality gates #18
• Split large architecture test files by semantic area #44

[iriswolf]

Design proposal

Direct conclusion

This issue should not become a broad physical split of the whole test suite before 1.0. That would create a large noisy diff with limited product value and a real risk of weakening existing regression coverage.

For 1.0.0-rc.1, the right scope is to make the test architecture explicit: taxonomy, ownership, parity expectations, coverage-readiness rules, and a concrete split map for the large mixed files. The large mechanical file split belongs to #44 and should happen incrementally after 1.0 or when a concrete area is touched.

This still satisfies the important part of #69: #18 can introduce meaningful coverage reporting without guessing which tests own which contracts.

Current audit

The test suite currently has one project:

• tests/TeleFlow.ArchitectureTests/TeleFlow.ArchitectureTests.csproj

That is acceptable for now. The problem is not the project count. The problem is that several files mix too many contracts and runtime scenarios:

• TelegramHandlerDispatcherTests.cs - about 4.6k lines, 160+ facts. Covers dispatcher behavior, routing, filters, error handlers, logging, route priority, callback matching, role/chat/thread filters.
• TelegramRuntimeIntegrationTests.cs - about 3.3k lines, 130+ facts. Covers bot registration, client request execution, JSON options, deep links, multipart, retries, long polling, context helpers, cancellation.
• TelegramHandlerGeneratorTests.cs - about 2.5k lines. Covers generator output, analyzer diagnostics, inherited metadata, callbacks, filters, state/scene generation, module diagnostics.
• StageSixStateAndMiddlewareTests.cs - about 1.4k lines. Covers state, state data, wizard, storage policies, middleware, rate limit middleware.
• StageEightGeneratedRegistrationTests.cs - about 1.6k lines. Covers generated registration, generated dispatch, generated error handlers, filters, state priority, modules, generated-only paths.
• StateStorageContracts/* already has the right shape: reusable contract-style tests for storage implementations. This should be treated as the model for future provider contracts.

The StageSix / StageEight names are also no longer good long-term names. They describe historical implementation stages, not current framework ownership.

Target taxonomy

Keep one test project for now, but document and gradually move toward semantic folders/classes:

1. PublicSurface

   • package graph
   • public namespaces
   • annotations contracts
   • API compatibility constraints
   • package smoke tests

2. TelegramClient

   • request executor
   • transport abstraction
   • Telegram response envelope parsing
   • typed exceptions and error mapping
   • retry-after policy
   • multipart uploads
   • generated low-level client methods
   • JSON options and wire names

3. FrameworkRuntime

   • application bootstrap
   • dispatcher execution
   • route selection and priority
   • handler invocation
   • filters
   • middleware
   • error handlers
   • current update/context accessors
   • dependency validation

4. CallbacksAndKeyboards

   • callback data metadata
   • generated callback codecs
   • callback route matching
   • keyboard builder behavior
   • raw string callback behavior
   • custom callback serialization boundaries

5. StateAndWizard

   • state lifecycle
   • state data lifecycle
   • wizard navigation
   • state key isolation
   • storage policy replacement
   • state middleware interaction with context

6. StateStorageContracts

   • reusable provider contract tests
   • memory provider implementation coverage
   • future Redis/Postgres provider contract reuse

7. GeneratedRegistration

   • generated handler registration
   • generated invokers
   • generated route/filter/state metadata
   • generated error handlers
   • generated vs direct/manual registration boundaries

8. AnalyzerAndGenerator

   • source generator output shape
   • analyzer diagnostics
   • invalid handler diagnostics
   • invalid callback/filter/state/scene/module diagnostics
   • inheritance and abstract base handling

9. Transports

   • raw long polling
   • framework long polling
   • raw webhooks
   • framework webhooks
   • offset, ack, cancellation, failure semantics

10. Hosting

    • hosted service integration
    • startup/shutdown tasks
    • DI/lifetime validation around hosted runtime

11. TestSupport

    • fake transports
    • recording loggers
    • generated registration probes
    • update builders
    • DI helpers
    • compiler/generator test helpers

Test ownership rules

• A test class should own one framework contract, not one historical milestone.
• New tests must be added under the semantic area that owns the behavior.
• Regression tests should stay near the contract they protect, even if the bug was found through another feature.
• Generator/analyzer tests should assert compile-time behavior; runtime dispatch tests should assert runtime behavior. Do not mix them unless the test explicitly checks generated-runtime parity.
• Reflection/generated parity tests should be explicit and named as parity tests. They should not be hidden inside ordinary dispatch tests.
• Storage providers must satisfy shared contract tests. Provider-specific tests may only cover provider-specific behavior.
• Coverage metrics must be interpreted by area. A high global percentage is not useful if dispatcher, state, callbacks, retry/error mapping, or generated registration are weak.

Relationship to #18 and #44

#69 should unblock #18 by defining what coverage means.

#18 should then add:

• coverlet collection in CI;
• stable coverage artifact generation;
• generated-code exclusions;
• no README badge until the coverage source is reliable;
• area-aware interpretation rules.

#44 should remain the physical split task. It should not block 1.0 unless one of the current large files becomes actively risky to change. The split should be incremental and behavior-preserving.

Recommended implementation for #69

1. Add tests/README.md with the taxonomy above.
2. Add a current-to-target ownership map for existing files.
3. Document the rules for where new tests must go.
4. Document the generated/reflection parity expectations.
5. Document coverage-readiness rules for Epic: Coverage reporting and quality gates #18.
6. Do not move large test files in this PR unless the move is tiny and obviously safe.
7. Do not change production code.
8. Do not add coverage thresholds in this issue.

Current-to-target split map

• TelegramHandlerDispatcherTests.cs -> FrameworkRuntime/Dispatching, FrameworkRuntime/Routing, FrameworkRuntime/Filters, FrameworkRuntime/ErrorHandling, FrameworkRuntime/Diagnostics, CallbacksAndKeyboards/CallbackRouting.
• TelegramRuntimeIntegrationTests.cs -> TelegramClient/*, Transports/LongPolling, FrameworkRuntime/Context, TelegramClient/RetryAndErrors, TelegramClient/Multipart, TelegramClient/Defaults.
• TelegramHandlerGeneratorTests.cs -> AnalyzerAndGenerator/Generator, AnalyzerAndGenerator/Analyzer, GeneratedRegistration/Metadata, CallbacksAndKeyboards/GeneratedCallbackCodecs.
• StageSixStateAndMiddlewareTests.cs -> StateAndWizard/*, FrameworkRuntime/Middleware, StateStorageContracts where applicable.
• StageEightGeneratedRegistrationTests.cs -> GeneratedRegistration/*, FrameworkRuntime/GeneratedDispatchParity, CallbacksAndKeyboards/GeneratedCallbackRouting.
• StateStorageContracts/* -> keep as-is and use as the model for future provider contracts.

Acceptance criteria for #69

• The repository has a documented test taxonomy before 1.0.0-rc.1.
• Existing large mixed files have an approved split map.
• New test placement rules are explicit.
• Generated/reflection parity rules are explicit.
• Coverage-readiness expectations are explicit enough for Epic: Coverage reporting and quality gates #18 to proceed.
• Split large architecture test files by semantic area #44 can later perform physical splitting without rediscovering the intended ownership model.

Non-goals

• No broad mechanical file split before 1.0.
• No production runtime changes.
• No coverage badge.
• No coverage threshold.
• No rewrite of existing tests just to make paths prettier.
• No new test projects unless Epic: Coverage reporting and quality gates #18 proves that separate projects are required for reliable coverage reporting.

Validation for the #69 PR

Expected validation is lightweight because the implementation should be documentation-only or near documentation-only:

• git diff --check
• targeted review of tests/README.md
• dotnet test tests/TeleFlow.ArchitectureTests/TeleFlow.ArchitectureTests.csproj only if any test/project files move or change