Skip to main content

Employee API Testing Guide

Summary​

Test Employee APIs in an approved, isolated environment with synthetic data and authorized tenant context. The source includes an Employee smoke script, but no formal .NET test project was found in the reviewed backend tree.

Audience​

  • QA and integration engineers
  • Backend and frontend developers
  • Solution architects reviewing cutover evidence

Prerequisites​

Use an approved isolated environment, synthetic records, a supported client, and authentication plus tenant context obtained through the approved environment process.

Test layers​

LayerConfirmed focus
Unit-level contract checksValidators, command/query result mapping, DTO serialization, GUID parsing, pagination normalization
Integration testsHandler plus persistence behavior under an isolated tenant, including success and rejection paths
Gateway testsPublic route selection, context forwarding, correlation continuity, safe 401/403 observation where the deployed boundary enforces it
Cutover/parity testsCompare supported compatibility operations against both destinations without assuming identical undocumented messages
Smoke testsCreate reference organization data, create/update/search an employee, change focused fields/status, retrieve timeline, exercise compatibility GUID routes, then clean up only test-owned data

The reviewed Employee smoke script covers both direct and compatibility modes. No dedicated Employee parity-comparison or cutover go/no-go script was found. The committed employee-service.http file contains only scaffold content and does not provide Employee API requests; use this reviewed reference instead of treating that file as a contract.

Coverage checklist​

  • Successful direct creation and update; assert 201/200, envelope, Location on create, and tenant isolation.
  • Required employee code, first name, and email; basic email format.
  • Duplicate employee code and duplicate email within one tenant.
  • Missing tenant context returns the documented direct 400 envelope.
  • Invalid or inactive department, designation, and manager.
  • Department/designation mismatch when a designation is department-specific.
  • Self-manager rejection on manager changes.
  • Employee not found for query and commands.
  • Status accepts only confirmed enum values.
  • Search filters, defaults, page-size cap, sorting fallback, and empty results.
  • Timeline retrieval for existing and missing employees.
  • Note text and document-reference required/non-negative fields.
  • Compatibility GUID acceptance and legacy numeric-ID rejection.
  • Compatibility response parity for the documented subset, including 200 create semantics.
  • Authorization outcomes: Requires confirmation because endpoint policies are not attached in source; verify the deployed gateway boundary without publishing sensitive mechanics.

Steps​

  1. Use a dedicated integration tenant and generated GUIDs.
  2. Obtain authentication and tenant context through the approved environment process.
  3. Create only uniquely prefixed synthetic records.
  4. Capture status, public response shape, and correlation identifier.
  5. Verify cross-tenant isolation with separately authorized test contexts.
  6. Remove only records created by the test when the API supports safe removal; otherwise use environment reset procedures.

Do not run mutation or cutover tests against production. Do not reproduce internal context shortcuts from repository scripts in client documentation.

Validation or Expected Result​

Each test must assert the documented HTTP status and body convention, correlation continuity where applicable, tenant isolation, and only the side effects confirmed for that operation. Parity tests should record intentional differences rather than require identical undocumented message text.

Troubleshooting​

Use the returned correlation identifier to trace approved logs. If authentication, tenant setup, or gateway destination cannot be confirmed, stop the test and ask the environment owner; do not substitute undocumented context mechanisms.

Source References​

  • microservices/scripts/smoke-employee.ps1
  • microservices/src/employee-service/employee-service.http
  • microservices/src/employee-service/Application/Validators/EmployeeCommandValidators.cs
  • microservices/src/employee-service/Api/EmployeeDirectEndpoints.cs
  • microservices/src/employee-service/Api/EmployeeCompatibilityEndpoints.cs
  • microservices/src/gateway-api/Program.cs

See Also​

Keywords​

  • API test coverage
  • Compatibility parity
  • Employee smoke tests

Revision Information​

  • Status: Draft
  • Last reviewed: 2026-07-15
  • Review cycle: Quarterly