Validation Module

Overview

This module provides comprehensive validation checklists to ensure the widget is production-ready before deployment.

Purpose: Quality assurance and completeness verification

Use: After all code, tests, and documentation are complete

Validation Categories

Code Quality - Architecture, patterns, best practices
Testing - Unit, hook, E2E tests
Documentation - AGENTS.md, ARCHITECTURE.md completeness
Integration - cc-widgets, sample apps
Manual Testing - Real-world usage verification

1. Code Quality Validation

Architecture & Layer Separation

Widget → Hook → Component → Store → SDK pattern followed
Widget component wrapped with observer HOC
Widget wrapped with ErrorBoundary
Hook contains all business logic
Component is pure presentational (if separate component)
No layer violations (Widget doesn't call SDK directly)
No component accessing store directly

MobX Integration

Widget uses observer HOC from mobx-react-lite
Store observables accessed correctly
Store mutations wrapped in runInAction
No direct store mutations outside runInAction
No reactions created in render

TypeScript

All types exported from types file
Props interface fully documented with JSDoc
No any types used (proper types everywhere)
Optional props marked with ?
Default values documented
Return types specified on functions
Complex types have interfaces/types
Exported types available to consumers

React Best Practices

Error Handling

ErrorBoundary wraps widget
Try-catch in all async operations
Errors logged to console
onError callback called on errors
User-friendly error messages displayed
Error recovery possible
No unhandled promise rejections

Code Style

Linting passes: yarn test:styles
No console.log statements (use proper logging)
Comments explain "why", not "what"
Complex logic documented
TODO comments removed
Dead code removed
Consistent naming conventions

Metrics & Logging

Widget wrapped with withMetrics HOC in index.ts
NOT wrapped with withMetrics in wc.ts
WIDGET_MOUNTED logged automatically
WIDGET_UNMOUNTED logged automatically
Custom metrics logged where appropriate

2. Functional Validation (NEW - CRITICAL)

Purpose

Verify that the widget actually WORKS as intended, not just that it compiles. Test the complete data flow from user action to UI update.

Sequence Diagram Validation

FIRST STEP: Load approved sequence diagrams from 01-pre-questions.md

Before running any tests, verify implementation matches approved diagrams:

Load all sequence diagrams from pre-questions
Load SDK API documentation from pre-questions
Load data transformation mappings from pre-questions

SDK Integration Test

Compare implemented code against approved sequence diagrams:

For each SDK method in sequence diagrams:

Method exists in contact-centre-sdk-apis/contact-center.json
Exact path matches sequence diagram (e.g., store.cc.someService.someMethod)
Parameters match diagram specification (type, order, values)
Return type matches SDK documentation AND diagram
Accessed via store.cc.methodName() (not direct import)
Error handling present (try/catch) as per error flow diagram
Success callbacks fire on success (verify timing per diagram)
Error callbacks fire on error (verify error path per diagram)
Response structure matches documented structure

Example Verification:

// From sequence diagram: store.cc.someService.someMethod(param1, param2)
// ✓ Exists in SDK JSON at exact path
// ✓ Parameters: (param1: value1, param2: value2) - matches diagram
// ✓ Return type: Promise<{statusCode: number, data: {...}}>
// ✓ Error handling: try/catch present with setError() call
// ✓ Callback: props.onSuccess?.(data) called on success
// ✓ Error callback: props.onError?.(error) called on failure
// ✓ Response accessed: response.data.items (matches diagram)

If method not found in SDK or signature mismatch → RETURN to sequence diagrams and fix

Data Transformation Validation:

Every transformation matches diagram mapping
Source fields extracted correctly (e.g., session.other.name)
Fallback values match diagram (e.g., || 'Unknown')
Type conversions correct (e.g., ISO string → timestamp)
Optional field handling matches diagram (?? operator)

Example:

// Diagram says: contactName = session.other.name || session.other.primaryDisplayString || 'Unknown'
// Code implements:
contactName: session.other?.name || session.other?.primaryDisplayString || 'Unknown'
// ✓ Matches diagram

Event Flow Test

Validate implementation against sequence diagrams:

For EACH sequence diagram, manually test the flow:

Testing Procedure

Load sequence diagram from pre-questions for scenario
Perform user action shown in diagram
Verify EACH step in diagram occurs in correct order
Check state updates match diagram timing
Confirm UI updates match diagram end state

Example: Button Click Flow (from sequence diagram)

Per diagram sequence:

User clicks button → Event handler called? ✓
Handler sets isLoading=true → State updated? ✓
Handler sets error=null → State cleared? ✓
Handler calls SDK method → Method invoked with correct params? ✓
SDK returns response → Response structure matches diagram? ✓
Handler transforms data → Transformation per diagram mappings? ✓
Handler sets data=records → State updated with transformed data? ✓
Handler sets isLoading=false → Loading state cleared? ✓
Component re-renders → UI shows new data? ✓

If ANY step fails or order wrong → Debug against sequence diagram

For YOUR widget, test ALL diagram scenarios:

Scenario 1: (from sequence diagram: _______________)

Diagram step → Implemented code → Verified?
───────────────────────────────────────────
User action: _______________     →  _______________  →  [ ]
Handler called: _______________  →  _______________  →  [ ]
State update 1: _______________  →  _______________  →  [ ]
State update 2: _______________  →  _______________  →  [ ]
SDK call: _______________        →  _______________  →  [ ]
SDK response: _______________    →  _______________  →  [ ]
Data transform: _______________  →  _______________  →  [ ]
Final state: _______________     →  _______________  →  [ ]
UI renders: _______________      →  _______________  →  [ ]

Overall Status: [ ] VERIFIED [ ] FAILED

Scenario 2: (from sequence diagram: _______________)

Diagram step → Implemented code → Verified?
───────────────────────────────────────────
User action: _______________     →  _______________  →  [ ]
Handler called: _______________  →  _______________  →  [ ]
State update 1: _______________  →  _______________  →  [ ]
State update 2: _______________  →  _______________  →  [ ]
SDK call: _______________        →  _______________  →  [ ]
SDK response: _______________    →  _______________  →  [ ]
Data transform: _______________  →  _______________  →  [ ]
Final state: _______________     →  _______________  →  [ ]
UI renders: _______________      →  _______________  →  [ ]

Overall Status: [ ] VERIFIED [ ] FAILED

Scenario 3: (from sequence diagram: _______________)

Diagram step → Implemented code → Verified?
───────────────────────────────────────────
User action: _______________     →  _______________  →  [ ]
Handler called: _______________  →  _______________  →  [ ]
State update 1: _______________  →  _______________  →  [ ]
State update 2: _______________  →  _______________  →  [ ]
SDK call: _______________        →  _______________  →  [ ]
SDK response: _______________    →  _______________  →  [ ]
Data transform: _______________  →  _______________  →  [ ]
Final state: _______________     →  _______________  →  [ ]
UI renders: _______________      →  _______________  →  [ ]

Overall Status: [ ] VERIFIED [ ] FAILED

Data Flow Test

Trace data through ALL layers:

User Action (UI)
  ↓
Widget Handler (index.tsx)
  ↓
Hook Method (helper.ts)
  ↓
Store/SDK Call
  ↓
Response/Observable Update
  ↓
Hook State Update
  ↓
Component Props
  ↓
UI Render

Verification:

User action triggers widget handler
Widget handler calls hook method correctly
Hook method accesses store/SDK correctly
Response updates hook state
Hook state passes to component props
Component renders with updated props
UI reflects the change

If any transition fails → Debug and fix

Import Validation Test

Check for circular dependencies:

# In widget code, search for cc-widgets import:
grep -r "from '@webex/cc-widgets'" packages/contact-center/{widget-name}/src/
# Expected: NO MATCHES

# In cc-components, search for widget imports:
grep -r "from '@webex/cc-.*-widget'" packages/contact-center/cc-components/src/
# Expected: NO MATCHES

Validation:

No matches for @webex/cc-widgets in widget code
No matches for widget packages in cc-components
All imports follow one-directional flow
No circular dependencies detected

If any matches found → Refactor imports

UI Visual Test

Compare with design input (Figma/screenshot/spec):

Colors match design (or use Momentum tokens)
Spacing matches (8px/0.5rem grid adhered)
Layout matches (flex/grid structure correct)
Components match design (correct Momentum components used)
Typography matches (sizes, weights correct)
Interactions work (hover, active, focus states)
Theme switching works (light/dark modes)

Visual differences found:

Element	Design	Generated	Status	Notes
_____	_____	_____	[ ] Fixed	_____
_____	_____	_____	[ ] Fixed	_____
_____	_____	_____	[ ] Fixed	_____

If visual mismatch → Update styling

Compiler Test

# Build the widget
yarn build

# Expected: NO ERRORS

Common compiler errors and fixes:

Error	Cause	Fix
Type error	Missing/incorrect types	Add proper type definitions
Import error	Wrong path or missing export	Check paths and exports
Circular dependency	Improper imports	Refactor to follow dependency flow
Syntax error	Code syntax issue	Fix syntax

Validation:

Fix ALL compiler errors before completing

Runtime Test (Manual)

Run sample app and test widget:

# Start React sample app
yarn samples:serve-react

Test checklist:

Test scenarios:

Happy Path:
- Primary user flow works end-to-end
- UI updates correctly
- Callbacks fire with correct data
Error Scenarios:
- Invalid input shows error message
- API errors handled gracefully
- Error callbacks fire
- User can recover from errors
Edge Cases:
- Empty state handled
- Loading state shown
- No data scenario handled
- Rapid clicks handled

If runtime errors → Debug and fix

3. Testing Validation

Unit Tests - Widget

Unit Tests - Hook

Test Quality

All tests pass: yarn test:unit
Test coverage > 80%
No skipped tests (.skip removed)
No focused tests (.only removed)
Tests are deterministic (not flaky)
Tests are independent (can run in any order)
Mock setup/teardown correct
No console warnings during tests
No console errors during tests

E2E Tests (Optional)

3. Documentation Validation

AGENTS.md Completeness

ARCHITECTURE.md Completeness

Documentation Quality

4. Integration Validation

cc-widgets Package

React Sample App

Web Component Sample App

5. Manual Testing Validation

Functional Testing

Visual Testing

Browser Testing

Chrome (latest)
Firefox (latest)
Safari (latest)
Edge (latest)

Accessibility Testing

Performance Testing

Error Scenarios

Invalid props handled gracefully
Missing props handled gracefully
SDK errors handled gracefully
Network errors handled gracefully
Empty data handled gracefully
User shown appropriate error message
Error logged to console
onError callback called

6. Build & Deploy Validation

Build Process

Widget builds successfully

cd packages/contact-center/{widget-name}
yarn build

No build errors
No build warnings
dist/ folder created
Types generated (dist/types/)
Source maps generated

Package Configuration

package.json name correct: @webex/cc-{widget-name}
package.json description correct
package.json version correct
package.json main points to dist/index.js
package.json types points to dist/types/index.d.ts
Dependencies correct
DevDependencies correct
PeerDependencies correct

File Structure

All required files present
No unnecessary files in dist/
README or link to docs present
License file present

7. Pattern Compliance

Check Against Pattern Docs

Naming Conventions

Widget name is kebab-case: agent-directory
Component name is PascalCase: AgentDirectory
File names match conventions
Function names are camelCase
Constants are UPPER_SNAKE_CASE
Types/Interfaces are PascalCase

8. Final Checklist

Code Complete

Quality Gates Passed

Integration Complete

cc-widgets updated
React sample updated
Web Component sample updated
Both samples tested

Documentation Complete

AGENTS.md complete
ARCHITECTURE.md complete
All examples tested
All diagrams render

Ready for Review

Issue Tracking

If any checklist items fail, document here:

Issues Found

Issue	Severity	Description	Solution	Status
1.	High/Med/Low	Description	Solution	Open/Fixed
2.	High/Med/Low	Description	Solution	Open/Fixed
3.	High/Med/Low	Description	Solution	Open/Fixed

Notes

(Add any notes about the validation process, workarounds, or decisions made)

Sign-Off

Validation completed by: _______________

Date: _______________

Widget name: _______________

Version: _______________

Status: ✅ READY FOR PRODUCTION / ⚠️ NEEDS WORK

Notes:

(Any final notes or observations)

Next Steps After Validation

If all checks pass:

Commit changes to version control
Create pull request
Request peer review
Update CHANGELOG
Prepare for release

If checks fail:

Document issues in tracking table
Fix issues
Re-run validation
Repeat until all checks pass

Template Version: 1.0.0 Last Updated: 2025-11-26

FilesExpand file tree

06-validation.md

Latest commit

History