User Acceptance Testing (UAT) Guide

Cross-References:

• Testing README - Testing overview and test pyramid
• E2E Test Scenarios - End-to-end test scenarios
• Test Data Strategy - General test data principles

Consolidation note (2026-04-10): This file now includes content previously in UAT_QUICK_REFERENCE.md and UAT_TEST_DATA_GUIDE.md.

​

Overview

• Validates business requirements are met
• Ensures user workflows function correctly
• Identifies usability issues before production
• Verifies multi-tenant isolation
• Confirms role-based access control
• Tests mobile responsiveness

​

UAT Process Overview

Planning → Preparation → Execution → Reporting → Sign-off

​

Phase 1: Planning (Week 1)

• Define UAT scope and objectives
• Identify test scenarios
• Assign testers and roles
• Set up UAT environment
• Prepare test data

​

Phase 2: Preparation (Week 1)

• Generate test cases from specifications
• Create test execution sessions
• Set up test data
• Validate environment readiness
• Train testers on tools and processes

​

Phase 3: Execution (Weeks 2-6)

• Execute test cases
• Document defects
• Track progress
• Update status regularly
• Conduct daily standups

​

Phase 4: Reporting (Week 7)

• Generate progress reports
• Analyze metrics
• Identify blockers
• Create executive summary
• Document lessons learned

​

Phase 5: Sign-off (Week 7)

• Review test results
• Address critical defects
• Obtain stakeholder approval
• Plan production deployment

​

Module-Agnostic Test Scenario Patterns

​

1. Happy Path Scenarios

• User performs primary action
• System processes correctly
• Expected result achieved
• Data saved correctly

​

2. Edge Cases

• Test with minimum data
• Test with maximum data
• Test with null/empty values
• Test with special characters
• Test with concurrent operations

​

3. Error Handling

• Invalid input validation
• Missing required fields
• Duplicate data prevention
• Constraint violations
• Network errors

​

4. Role-Based Access Control

• Admin can perform all actions
• Manager can perform department-scoped actions
• Employee can view own data only
• Unauthorized access is blocked

​

5. Multi-Tenant Isolation

• User from Org A cannot see Org B data
• User from Org A cannot modify Org B data
• Cross-organization queries return empty
• Data creation scoped to user’s organization

​

6. Mobile Responsiveness

• Test on mobile viewport (< 768px)
• Verify touch targets (44x44px minimum)
• Test navigation (bottom tab bar)
• Verify forms are usable
• Test data tables (horizontal scroll if needed)

​

Module-Specific Test Scenarios

​

HR (Workforce & HRIS) - Priority 1

• HR-01: Employee Directory & Org Structure
• HR-02: Credentialing & Compliance
• HR-03: Onboarding & Offboarding
• HR-04: Scheduling & Capacity
• HR-05: Time & Attendance
• HR-06: PTO & Leave Management
• HR-10: Performance Management
• HR-11: Benefits Administration
• HR-12: Employee Self-Service
• HR-13: Skills & Competencies
• HR-15: Compensation Management

• Employee creation and onboarding workflow
• Credential upload and expiration tracking
• Shift creation and assignment
• Time punch in/out and timesheet approval
• Leave request and approval workflow
• Performance review lifecycle
• Benefits enrollment
• Skills gap analysis

​

FA (Finance & Accounting) - Priority 2

• FA-01: Chart of Accounts
• FA-02: General Ledger
• FA-03: Accounts Payable
• FA-04: Accounts Receivable
• FA-05: Budgeting & Forecasting
• FA-06: Financial Reporting
• FA-07: Bank Reconciliation
• FA-08: Fixed Assets

• Invoice creation and approval
• Payment processing
• Journal entry posting
• Budget creation and tracking
• Financial report generation
• Bank reconciliation workflow

​

RH (Recovery Housing) - Priority 2

• RH-01: Census & Beds
• RH-02: Resident Management
• RH-03: Phase Progression
• RH-04: Program Management
• RH-05: Incident Reporting
• RH-06: Compliance Reporting
• RH-07: Outcomes & Alumni

• Resident admission workflow
• Bed assignment and tracking
• Phase progression tracking
• Incident creation and reporting
• Compliance report generation

​

GR (Governance & Compliance) - Priority 3

• GR-01: Policy Management
• GR-02: Training & Certification
• GR-03: Regulatory Requirements
• GR-04: Audit Management
• GR-05: Risk Management
• GR-06: Quality Improvement
• GR-07: Contract Management
• GR-08: Accreditation Management

• Policy creation and acknowledgment
• Training assignment and completion
• Audit lifecycle (create → execute → complete)
• Risk assessment and mitigation
• Corrective action tracking

​

FW (Forms & Workflow) - Priority 3

• FW-01: Form Builder
• FW-02: Form Submissions
• FW-03: Automation Engine
• FW-05: Multi-Page Forms
• FW-06: Approval Gates
• FW-07: Workflow Versioning

• Form creation and publishing
• Form submission (authenticated and public)
• Automation rule triggering
• Approval workflow
• Form version rollback

​

FM (Facilities Management) - Priority 4

• FM-01: Asset Management
• FM-02: Preventive Maintenance
• FM-03: Work Orders
• FM-04: Inventory Management
• FM-05: Vendor Management
• FM-06: Compliance Inspections

• Asset creation and tracking
• PM schedule creation
• Work order creation and completion
• Inventory item management
• Vendor contract management

​

LO (Leadership Operating System) - Priority 4

• LO-01: Vision & Rocks
• LO-02: Meeting Management
• LO-03: Scorecards
• LO-04: Issues Tracking
• LO-05: People Analyzer
• LO-06: Accountability Chart

• Rock creation and tracking
• Meeting creation and minutes
• Scorecard updates
• Issue creation and resolution

​

IT (IT Asset & Service Management) - Priority 4

• IT-01: Asset Management
• IT-02: Ticketing System
• IT-03: Software Licenses
• IT-04: Vendor Management
• IT-05: Procurement
• IT-06: Change Management

• IT asset creation and tracking
• Ticket creation and resolution
• License tracking and renewal
• Procurement request workflow

​

PF (Platform Foundation) - Priority 5

• PF-01: Organizations & Sites
• PF-02: User Roles & Permissions
• PF-06: User Profiles
• PF-10: Notifications
• PF-11: Document Management
• PF-12: Reporting Engine

• Organization onboarding
• User invitation and role assignment
• Document upload and permissions
• Notification delivery
• Report creation and execution

​

Roles and Responsibilities

​

UAT Coordinator

• Responsibilities:
  • Plan and coordinate UAT activities
  • Manage test case assignments
  • Track progress and report status
  • Facilitate defect triage
  • Generate UAT reports

​

Testers

• Responsibilities:
  • Execute assigned test cases
  • Document test results
  • Report defects with details
  • Verify defect fixes
  • Provide feedback on usability

​

Business Analysts

• Responsibilities:
  • Validate test scenarios cover requirements
  • Clarify business rules
  • Review test results
  • Approve sign-off criteria

​

Developers

• Responsibilities:
  • Fix defects identified in UAT
  • Provide technical clarification
  • Support test environment
  • Verify fixes before retest

​

Product Owner

• Responsibilities:
  • Define UAT scope and priorities
  • Review and approve test scenarios
  • Make go/no-go decisions
  • Sign off on UAT completion

​

Success Criteria and Metrics

​

Overall Success Criteria

• 95%+ of critical test cases pass
• Zero critical defects (data loss, security breaches)
• <5% of test cases blocked by blockers
• All multi-tenant isolation tests pass
• All role-based access tests pass

• 90%+ of high-priority test cases pass
• <10% of test cases blocked
• User satisfaction score ≥4.0/5.0
• Performance targets met

• 85%+ of all test cases pass
• Mobile responsiveness verified
• Cross-module integration tested

​

Key Metrics

• Total test cases: [Count]
• Test cases executed: [Count]
• Test cases passed: [Count]
• Test cases failed: [Count]
• Test cases blocked: [Count]
• Test cases skipped: [Count]
• Pass rate: [Percentage]

• Total defects: [Count]
• Critical defects: [Count]
• High defects: [Count]
• Medium defects: [Count]
• Low defects: [Count]
• Defects fixed: [Count]
• Defects open: [Count]

• Days in UAT: [Count]
• Test cases per day: [Average]
• Defects per day: [Average]
• Estimated completion: [Date]

• Page load time: <3s (p95)
• API response time: <500ms (p95)
• Database query time: <200ms (p95)

​

Templates Reference

​

Test Case Template

• Test Case ID
• Feature/Module
• Test Scenario Name
• Priority
• Preconditions
• Test Steps
• Expected Results
• Test Data Requirements
• Pass/Fail Criteria

​

Test Execution Checklist

• Session information
• Test case execution status
• Notes and issues
• Screenshots

​

Defect Report Template

• Defect ID
• Test Case ID
• Severity and Priority
• Steps to Reproduce
• Expected vs Actual
• Environment details

​

Progress Dashboard Template

• Overall metrics
• Feature-wise breakdown
• Test execution summary
• Defect summary
• Risk assessment

​

Cursor Commands Reference

​

generate-uat-test-cases

# Generate test cases for HR module
generate-uat-test-cases --module hr

# Generate test cases for all modules
generate-uat-test-cases --all

​

create-uat-session

# Create session for HR module
create-uat-session --tester "John Doe" --module hr

# Create session for specific feature
create-uat-session --tester "Jane Smith" --feature HR-02

​

track-uat-progress

# Track progress for specific session
track-uat-progress --session docs/testing/uat/execution-logs/session-2026-01-15/

# Track all sessions and update dashboard
track-uat-progress --all --update-dashboard

​

create-uat-defect

# Create defect for test case
create-uat-defect --test-case HR-UAT-042 --severity high

​

generate-uat-report

# Generate report for HR module
generate-uat-report --module hr --output reports/uat/

# Generate report for all modules
generate-uat-report --all --format html

​

export-uat-csv

# Export specific session
export-uat-csv --session docs/testing/uat/execution-logs/session-2026-01-15/

# Export all sessions
export-uat-csv --all --output docs/testing/uat/exports/

​

generate-uat-test-data

# Generate HR test data
generate-uat-test-data --module hr --orgs 2 --employees 50

# Generate test data for all modules
generate-uat-test-data --all --orgs 2

​

validate-uat-readiness

# Validate HR module readiness
validate-uat-readiness --module hr

# Validate all modules
validate-uat-readiness --all

​

Automation Scripts

​

Test Case Generator

npm run uat:generate-test-cases -- --module hr
npm run uat:generate-test-cases -- --module fa
npm run uat:generate-test-cases -- --all

​

Test Data Generator

npm run uat:generate-test-data -- --module hr --orgs 2 --employees 50
npm run uat:generate-test-data -- --all --orgs 2

​

Progress Tracker

npm run uat:track-progress -- --input docs/testing/uat/execution-logs/

​

Report Generator

npm run uat:generate-report -- --output reports/uat/

​

Best Practices

​

Test Execution

1. Follow Test Cases: Execute test cases as written, don’t skip steps
2. Document Everything: Record all observations, even if test passes
3. Take Screenshots: Capture screenshots for defects and key steps
4. Report Immediately: Don’t wait to report defects
5. Verify Fixes: Re-test defects after fixes are deployed

​

Defect Reporting

1. Be Specific: Include exact steps to reproduce
2. Include Context: Provide environment, browser, user role
3. Attach Evidence: Screenshots, logs, error messages
4. Prioritize Correctly: Use severity and priority appropriately
5. Follow Up: Track defect status and verify fixes

​

Progress Tracking

1. Update Daily: Update progress tracking daily
2. Be Honest: Report blockers and issues immediately
3. Communicate: Share progress in daily standups
4. Identify Risks: Flag risks early
5. Celebrate Wins: Acknowledge completed features

​

Test Data

1. Use Synthetic Data: Never use real PHI/PII
2. Be Realistic: Test data should reflect real-world scenarios
3. Clean Up: Remove test data after UAT completion
4. Document: Document test data setup for reproducibility
5. Isolate: Use separate test organizations

​

Common Issues and Solutions

​

Issue: Test Environment Not Ready

​

Issue: Missing Test Data

​

Issue: Test Cases Not Generated

​

Issue: Progress Not Updating

​

Issue: Can’t Export to CSV

​

Test Data Setup

​

Key Principles

• Synthetic data only (no PHI/PII)
• Multi-tenant setup (2+ test organizations)
• Realistic scenarios (healthcare context)
• Isolated from production

​

Multi-Tenant Setup Requirements

​

Module-Specific Test Data Requirements

​

Automated Generation

# Generate base platform data first
npm run uat:generate-test-data -- --module pf --orgs 2

# Generate module-specific data
npm run uat:generate-test-data -- --module hr --orgs 2 --employees 50
npm run uat:generate-test-data -- --all --orgs 2

​

Synthetic Data Guidelines

​

Quick Reference Checklist

​

Before UAT

• validate-uat-readiness --module {module}
• generate-uat-test-data --module {module} --orgs 2
• generate-uat-test-cases --module {module}
• Review test scenarios in docs/testing/uat/{module}-test-scenarios.md
• create-uat-session --tester "Name" --module {module}

​

During UAT

• Execute test cases, document Pass/Fail/Blocked/Skipped
• create-uat-defect --test-case {ID} --severity {level}
• track-uat-progress --session {path}

​

After UAT

• generate-uat-report --module {module} --output reports/uat/
• export-uat-csv --session {path}
• Review metrics, obtain stakeholder sign-off

​

Defect Severity

​

Related Documentation

• Testing README - Testing overview and test pyramid
• E2E Test Scenarios - End-to-end test scenarios
• Test Data Strategy - Test data principles

​

Version History

​

2.0.0 (2026-04-10)

• Consolidated UAT_QUICK_REFERENCE.md and UAT_TEST_DATA_GUIDE.md into this file
• Added test data setup section and quick reference checklist

​

1.0.0 (2026-01-15)

• Initial UAT Guide created