UKHO.GitHubCopilot.ToolKit tests.instructions.md

Test approach (unit, integration, E2E, functional)

Overview

These instructions define how automated tests are structured and authored in this repository. Prefer fast, isolated unit tests. Add integration and end-to-end tests for cross-boundary behavior where needed. Add functional tests to validate documented requirements. The framework and suite-shape choices in this file are repository defaults unless a documented exception applies.

Scope

Applies to: test/**/*.cs, test/**/*.csproj

• Applies when creating or updating any test projects or test code under test/.
• The framework and structure choices in this file are defaults for repository test work unless a narrower file or an explicitly documented exception applies.
• When a work item needs a justified deviation from these defaults, document the reason in the relevant project or work-package documentation so the deviation remains reviewable.
• These rules are additive to:
  • /.github/instructions/folders.instructions.md
  • /.github/instructions/playwright.instructions.md
  • /.github/instructions/work-packages.instructions.md

Instructions

MUST

• Keep all automated tests under test/.

• Use xUnit for unit test projects by default.

• All new non-trivial code MUST be covered with unit tests.

  • Where legacy code, generated code, boilerplate, or other constraints make unit testing impractical, any exclusion MUST be a conscious and reviewable team decision.

• Prefer unit tests over higher-level tests when a behavior can be validated without infrastructure.

• Standardize test project structure as: test/<Service>/<Service>.<TestType>/...

  • Use separate projects per test type so suites can be run independently:
    • test/<Service>/<Service>.UnitTests
    • test/<Service>/<Service>.IntegrationTests
    • test/<Service>/<Service>.E2ETests
    • test/<Service>/<Service>.FunctionalTests

• Use descriptive test file names that match the contained test class; avoid generic names like UnitTest1.cs.

• Automated test method names MUST follow the MethodName_StateUnderTest_ExpectedResult convention.

  • Prefer names that read as natural English, typically using Should... for the expected result and When... for the state under test.
  • Example: CalculateTotal_ShouldReturnZero_WhenCartIsEmpty

• Automated tests MUST be fully documented with comments immediately above each test method.

  • Test comments MUST capture requirement traceability when applicable, using identifiers from the relevant work package or requirement source (for example FR1, NF2, SR3, TR1).
  • Test comments MUST explain what the test is verifying, the expected outcome, and why the behavior matters or regression risk it is guarding against.
  • When the scenario is not obvious from the method name alone, test comments MUST also explain important setup assumptions or boundary conditions.
  • Prefer XML documentation comments (///) when the language and test framework support them cleanly.