EnvelopeGenerator/TESTING_CHECKLIST.md

DevExpress v25.2.3 - Testing Checklist

Important: This checklist has been updated according to the verified real API for v25.2.3. GoToPageAsync(), PageNumberChanged, ZoomLevelChanged, ToolbarVisible do NOT exist.

Build Status

• Build: Successful
• DevExpress Version: 25.2.3
• Strategy: CustomizeToolbar + manual state tracking

---

Test Scenarios

1. PDF Loading

• PDF document loads successfully
• DevExpress PdfViewer displays the document
• _pdfViewer.PageCount > 0 check passes
• _totalPages = _pdfViewer.PageCount gets correct value (no JS call needed)
• _pdfLoaded = true is set
• Toolbar is visible and shows correct page count (e.g., "Page 1 / 5")
• Zoom level displays correctly (e.g., "150%") – if _viewerZoomLevel = 1.5

2. CustomizeToolbar Navigation

• Previous Page button (◀) works and updates page counter
• Next Page button (▶) works and updates page counter
• Previous button is disabled on page 1
• Next button is disabled on last page
• Page counter updates correctly (e.g., "Page 2 / 5")
• Each navigation button's Click handler calls RenderSignatureButtonsAsync()

3. CustomizeToolbar Zoom

• Zoom In button (+) increases zoom
• Zoom Out button (−) decreases zoom
• _viewerZoomLevel = _currentZoom / 100d is calculated (150 → 1.5)
• Viewer does NOT display "15000%" (incorrect value detection)
• Zoom is constrained to 50% - 300% range
• PDF viewer zoom level changes visually

4. Signature Overlay Rendering

• Signature placeholders appear on correct pages
• Overlays are positioned correctly over the PDF
• Overlays re-render after page changes
• Overlays re-render after zoom changes
• Overlay sizes scale with zoom level

5. Signature Navigation

• Custom signature toolbar is visible (if signatures exist)
• Previous/Next signature buttons work
• Signature counter shows correct values (e.g., "0 / 3")
• "X open" badge shows unsigned count
• Cross-page navigation: _currentPage updates and overlays refresh
• ⚠ Known limitation: DxPdfViewer visible page cannot be changed programmatically

6. Thumbnail Sidebar

• Thumbnails render (may take a few seconds)
• Thumbnail click updates _currentPage state
• Thumbnail click refreshes overlays
• ⚠ Known limitation: Thumbnail click does not navigate DevExpress viewer
• Active thumbnail is highlighted correctly

7. Signature Capture & Application

• Signature popup opens on first load (if no cache)
• Draw signature works
• Text signature works
• Image upload signature works
• Clicking signature placeholder applies signature
• Applied signature overlays are positioned correctly
• Counter updates after signature applied (e.g., "1 / 3")

8. Known Limitations (v25.2.3 API Limit)

• ⚠ User cannot scroll PDF to change pages (only CustomizeToolbar buttons)
• ⚠ Thumbnail clicks do not navigate viewer (only update state)
• ⚠ Browser zoom gestures do not trigger overlay updates
• ✓ Custom toolbar buttons correctly trigger overlay updates
• ✓ _pdfViewer.PageCount eliminates need for JS getTotalPages() call
• ✓ ZoomLevel = _currentZoom / 100d calculates correct zoom factor

---

Common Issues

Issue: Toolbar not visible

Reason: _pdfLoaded = false or _totalPages = 0
Solution: In OnAfterRenderAsync, check _pdfViewer.PageCount > 0, set _pdfLoaded = true

if (_pdfViewer is not null && _pdfViewer.PageCount > 0)
{
    _totalPages = _pdfViewer.PageCount;  // no JS call needed
    _pdfLoaded = true;
    await InvokeAsync(StateHasChanged);
}

Issue: Signature overlays not visible

Reason: RenderSignatureButtonsAsync() not called after page/zoom change
Solution: Verify each button Click handler in OnCustomizeToolbar calls RenderSignatureButtonsAsync()

Issue: Page navigation not working

Reason: OnCustomizeToolbar button Click lambdas not updating _currentPage
Solution: Check that each button updates _currentPage and calls StateHasChanged() and RenderSignatureButtonsAsync()

Issue: Zoom not working or showing "15000%"

Reason: Incorrect value assigned to _viewerZoomLevel
Solution: _viewerZoomLevel = _currentZoom / 100d – ZoomLevel takes factor, not percentage

// CORRECT
_currentZoom = 150;               // UI display: "150%"
_viewerZoomLevel = 150 / 100d;    // Pass to DxPdfViewer: 1.5

// WRONG
_viewerZoomLevel = 150;           // DxPdfViewer displays "15000%"

Issue: Total page count is 0

Reason: JS call made before timing or fails
Solution: Use _pdfViewer.PageCount directly, no need for pdfViewer.getTotalPages() JS call

---

Success Criteria

Minimum working functionality:

• PDF loads and displays
• _totalPages = _pdfViewer.PageCount gets correct page count
• Custom toolbar navigation works (previous/next/zoom)
• Signature overlays render on current page
• Signature capture and application works
• Overlays update after navigation/zoom

Known acceptable limitations (v25.2.3 API limit):

• Thumbnail clicks do not navigate viewer (only update state)
• User scroll/native toolbar navigation does not update C# state
• Cross-page signature navigation is limited

---

Next Steps If All Tests Pass

1. Remove debug toolbar button (if present)
2. Clean up unused code comments
3. Update user documentation about navigation limitations

---

Architecture Reference: Verified v25.2.3 API

Property	Access	Usage
DocumentContent	[Parameter] GET/SET	Feed PDF with byte[]
ZoomLevel	[Parameter] GET/SET	Factor: _currentZoom / 100d
IsSinglePagePreview	[Parameter] GET/SET	true = single page mode
PageCount	GET only	Total pages – no JS needed
ActivePageIndex	GET only	Active page index (0-based) – no SET
CssClass	[Parameter] GET/SET	Assign CSS class
SizeMode	[Parameter] GET/SET	Small / Medium / Large
DocumentName	[Parameter] GET/SET	Download filename

Not available: GoToPageAsync(), PageNumberChanged, ZoomLevelChanged, ToolbarVisible