> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# User Acceptance Testing (UAT) Guide

> User Acceptance Testing (UAT) validates that the Encore OS Platform meets business requirements from the end-user perspective. This guide describes how to cond…

**Version:** 2.0.0\
**Last Updated:** 2026-04-10\
**Status:** Active\
**Module:** All Modules (PF, HR, FA, RH, GR, FW, FM, LO, IT)

> **Cross-References:**
>
> * [Testing README](/testing/index) - Testing overview and test pyramid
> * [E2E Test Scenarios](/testing/E2E_TEST_SCENARIOS) - End-to-end test scenarios
> * [Test Data Strategy](/testing/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

User Acceptance Testing (UAT) validates that the Encore OS Platform meets business requirements from the end-user perspective. This guide describes how to conduct UAT across all platform modules.

**Why UAT Matters:**

* 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

**Starting Point:** HR module serves as the initial UAT focus, with the framework designed to scale to all modules (PF, HR, FA, RH, GR, FW, FM, LO, IT).

***

## UAT Process Overview

The UAT process follows these phases:

```text theme={null}
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

These patterns apply to all modules and should be tested for each feature:

### 1. Happy Path Scenarios

**Purpose:** Verify core functionality works as designed

**Pattern:**

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

**Example (HR):** Employee creation → Record saved → Employee appears in directory
**Example (FA):** Invoice creation → Invoice saved → Invoice appears in list

### 2. Edge Cases

**Purpose:** Verify system handles boundary conditions

**Pattern:**

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

**Example (HR):** Create employee with minimal required fields
**Example (FA):** Create invoice with zero amount (if allowed)

### 3. Error Handling

**Purpose:** Verify graceful error handling

**Pattern:**

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

**Example (HR):** Attempt to create duplicate employee number
**Example (FA):** Attempt to post transaction with invalid account

### 4. Role-Based Access Control

**Purpose:** Verify permissions are enforced

**Pattern:**

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

**Example (HR):** Manager views only direct reports
**Example (FA):** Finance admin can approve, staff cannot

### 5. Multi-Tenant Isolation

**Purpose:** Verify tenant data isolation

**Pattern:**

* 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

**Example (HR):** Org A user cannot see Org B employees
**Example (FA):** Org A user cannot see Org B transactions

### 6. Mobile Responsiveness

**Purpose:** Verify mobile-first design

**Pattern:**

* 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)

**Example (HR):** Employee directory on mobile
**Example (FA):** Invoice creation on mobile

***

## Module-Specific Test Scenarios

### HR (Workforce & HRIS) - Priority 1

**Features to Test:**

* 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

**Key Test Scenarios:**

* 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

**See:** HR Test Scenarios for detailed scenarios

### FA (Finance & Accounting) - Priority 2

**Features to Test:**

* 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

**Key Test Scenarios:**

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

### RH (Recovery Housing) - Priority 2

**Features to Test:**

* 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

**Key Test Scenarios:**

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

### GR (Governance & Compliance) - Priority 3

**Features to Test:**

* 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

**Key Test Scenarios:**

* 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

**Features to Test:**

* 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

**Key Test Scenarios:**

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

### FM (Facilities Management) - Priority 4

**Features to Test:**

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

**Key Test Scenarios:**

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

### LO (Leadership Operating System) - Priority 4

**Features to Test:**

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

**Key Test Scenarios:**

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

### IT (IT Asset & Service Management) - Priority 4

**Features to Test:**

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

**Key Test Scenarios:**

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

### PF (Platform Foundation) - Priority 5

**Features to Test:**

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

**Key Test Scenarios:**

* 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

**Must Have:**

* 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

**Should Have:**

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

**Nice to Have:**

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

### Key Metrics

**Test Execution 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]

**Defect Metrics:**

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

**Progress Metrics:**

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

**Performance Metrics:**

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

***

## Templates Reference

### Test Case Template

**Location:** [templates/UAT\_TEST\_CASE\_TEMPLATE.md](https://github.com/Encore-OS/encoreos/blob/development/docs/testing/templates/UAT_TEST_CASE_TEMPLATE.md)

Use this template to create individual test cases. Each test case should include:

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

### Test Execution Checklist

**Location:** [templates/UAT\_EXECUTION\_CHECKLIST\_TEMPLATE.md](https://github.com/Encore-OS/encoreos/blob/development/docs/testing/templates/UAT_EXECUTION_CHECKLIST_TEMPLATE.md)

Use this template to track test execution sessions. Includes:

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

### Defect Report Template

**Location:** [templates/UAT\_DEFECT\_REPORT\_TEMPLATE.md](https://github.com/Encore-OS/encoreos/blob/development/docs/testing/templates/UAT_DEFECT_REPORT_TEMPLATE.md)

Use this template to report defects found during UAT. Includes:

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

### Progress Dashboard Template

**Location:** [templates/UAT\_PROGRESS\_DASHBOARD\_TEMPLATE.md](https://github.com/Encore-OS/encoreos/blob/development/docs/testing/templates/UAT_PROGRESS_DASHBOARD_TEMPLATE.md)

Use this template to track overall UAT progress. Includes:

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

***

## Cursor Commands Reference

The following Cursor commands simplify UAT workflows:

### `generate-uat-test-cases`

Generate test cases from specification files automatically.

```bash theme={null}
# 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 a new UAT execution session with checklist template.

```bash theme={null}
# 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`

Update progress tracking from execution logs.

```bash theme={null}
# 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 a defect report from template with auto-numbering.

```bash theme={null}
# Create defect for test case
create-uat-defect --test-case HR-UAT-042 --severity high
```

### `generate-uat-report`

Generate UAT summary report with metrics and charts.

```bash theme={null}
# 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 markdown checklists to CSV for stakeholder sharing.

```bash theme={null}
# 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 synthetic test data for UAT environment.

```bash theme={null}
# 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 UAT environment and test data readiness.

```bash theme={null}
# Validate HR module readiness
validate-uat-readiness --module hr

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

**See:** [.cursor/README.md](https://github.com/Encore-OS/encoreos/blob/development/.cursor/README.md) for complete command reference

***

## Automation Scripts

### Test Case Generator

**Location:** `scripts/uat/generate-test-cases.ts`

Automatically generates test cases from specification files.

**Usage:**

```bash theme={null}
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

**Location:** `scripts/uat/generate-test-data.ts`

Generates synthetic test data for UAT environment.

**Usage:**

```bash theme={null}
npm run uat:generate-test-data -- --module hr --orgs 2 --employees 50
npm run uat:generate-test-data -- --all --orgs 2
```

### Progress Tracker

**Location:** `scripts/uat/track-progress.ts`

Updates progress tracking from execution logs.

**Usage:**

```bash theme={null}
npm run uat:track-progress -- --input docs/testing/uat/execution-logs/
```

### Report Generator

**Location:** `scripts/uat/generate-report.ts`

Generates UAT summary reports with metrics.

**Usage:**

```bash theme={null}
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

**Solution:** Run `validate-uat-readiness` command to check environment status

### Issue: Missing Test Data

**Solution:** Run `generate-uat-test-data` command to create test data

### Issue: Test Cases Not Generated

**Solution:** Run `generate-uat-test-cases` command from spec files

### Issue: Progress Not Updating

**Solution:** Run `track-uat-progress` command to update from execution logs

### Issue: Can't Export to CSV

**Solution:** Run `export-uat-csv` command to convert markdown 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

**Minimum:** 2 test organizations, 3-5 sites each, 10-20 test users each, 50-100 employees each.

**Test User Naming:** `uat-{role}-{org}-{number}@test.encoreos.io`

### Module-Specific Test Data Requirements

| Module | Key Data Volumes                                                           |
| ------ | -------------------------------------------------------------------------- |
| HR     | 50-100 employees, 5-10 departments, 20-30 credentials, 50-100 time punches |
| FA     | Chart of accounts, 50-100 transactions, 20-30 invoices, 10-15 vendors      |
| RH     | 20-30 residents, 10-15 beds, 5-10 programs, 5-10 incidents                 |
| GR     | 10-15 policies, 20-30 training assignments, 5-10 audits                    |
| FW     | 10-15 forms, 50-100 submissions, 10-15 automation rules                    |
| FM     | 20-30 assets, 20-30 work orders, 50-100 inventory items                    |
| LO     | 20-30 rocks, 10-15 meetings, 10-15 scorecards                              |
| IT     | 20-30 IT assets, 50-100 tickets, 10-15 software licenses                   |
| PF     | Organizations, sites, users (base data), 20-30 documents                   |

### Automated Generation

```bash theme={null}
# 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

**Never use** real patient names, SSNs, addresses, medical record numbers, or insurance info. **Always use** faker-generated synthetic data with obvious test values (e.g., `(555) 123-4567`, `test@example.com`).

***

## 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

| Severity     | Impact                                      | Example                       |
| ------------ | ------------------------------------------- | ----------------------------- |
| **Critical** | System unusable, data loss, security breach | Cannot login, data corruption |
| **High**     | Major feature broken, workaround exists     | Feature not working           |
| **Medium**   | Minor feature issue                         | UI glitch, non-critical error |
| **Low**      | Cosmetic                                    | Typo, minor UI improvement    |

***

## Related Documentation

* [Testing README](/testing/index) - Testing overview and test pyramid
* [E2E Test Scenarios](/testing/E2E_TEST_SCENARIOS) - End-to-end test scenarios
* [Test Data Strategy](/testing/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

***

**Maintained by:** Platform QA Team