Testing Strategy

← Back to Index

Priority: Automated tests FIRST, manual testing as supplementary safety net.

Philosophy: Automated Tests Are Primary

Before writing ANY refactoring code:

Write comprehensive automated tests for current behaviour
Verify tests pass (establish baseline)
Make refactoring changes
Tests still pass (green to green refactoring)
(Optional) Run manual testing checklist for extra confidence

Why automated tests first?

Immediate feedback on every change
No manual clicking through scenarios
Runs in CI/CD on every commit
Documents expected behaviour
Prevents regressions permanently

Required Automated Test Coverage

Before Starting Any Phase

You MUST have automated tests covering:

Context Unit Tests

File: content/webapp/contexts/ItemViewerContextV2/ItemViewerContextV2.test.tsx

Test ALL derived values:

Test all edge cases:

Undefined transformedManifest
Empty canvases array
Canvas without imageServiceId
Canvas without probeServiceId (non-restricted)
Canvas with probeServiceId (restricted)
Invalid canvas index (too high)
Null/undefined values

New (from restricted-images merge):

isCurrentCanvasRestricted returns true for restricted canvas
isCurrentCanvasRestricted returns false for non-restricted canvas
currentProbeServiceId extracted correctly when present
currentProbeServiceId is undefined when absent

Component Integration Tests

Files: Component .refactored.test.tsx files

Test that components actually consume context values:

Download Options Hook Tests (Phase 2)

File: content/webapp/hooks/useDownloadOptions.test.ts

Test download option calculations:

Test edge cases:

Multiple downloads with different URLs (all included)
Multiple downloads with same URL (only one included after dedup)
ChoiceBody in rendering array
ChoiceBody in supplementing array
Empty download arrays
Restricted downloads for staff vs non-staff users

Mock Utilities

File: content/webapp/contexts/ItemViewerContextV2/test-utils.ts

mockDefaultContext with proper TypeScript types
Helper functions for creating test manifests
Helper functions for creating test canvases
All mocks properly typed (no any)

Test Examples

See refactoring-iiif-viewer-context-testing.md for complete TypeScript test examples.

Quick example:

describe('ItemViewerContextV2 - Derived Canvas Data', () => {
  it('should calculate currentCanvasIndex from canvas query param', () => {
    const contextValue: ItemViewerContextV2Props = {
      ...mockDefaultContext,
      query: { canvas: 3, manifest: 1, page: 1, shouldScrollToCanvas: true, query: '' },
      currentCanvasIndex: 2, // canvas=3 to index 2 (1-indexed to 0-indexed)
    };

    render(
      <ItemViewerContextV2.Provider value={contextValue}>
        <ContextValueDisplay />
      </ItemViewerContextV2.Provider>
    );

    expect(screen.getByTestId('currentCanvasIndex')).toHaveTextContent('2');
  });
});

Manual Testing Checklist

Use this AFTER automated tests pass as an extra safety net.

For Each Phase: Core Functionality

Different Work Types

Test with these specific work types:

User Scenarios Matrix

The table below lists key combinations of work types, authentication states, and access restrictions. Test coverage should span these scenarios to ensure the viewer handles all cases correctly.

Authentication States:

Logged out - no authentication
Logged in (regular user) - standard library member
Logged in (restricted access) - user with restricted content access (same UI, different access level)

Access Types:

✓ Open access - no restrictions
🔒 Restricted - requires authentication with restricted access role
⚠️ Content advisory - requires clicking through warning modal (any auth state)

Work Type

Logged Out

Logged In (Regular)

Logged In (Restricted)

Example Work ID

Notes

Multi-canvas images

✓ Open

a55dcp3h

Grid view, navigation

Single canvas image

✓ Open

b5kqccbb

No grid/nav controls

Archive items

✓ Open

a222zvge

Tree navigation

Video/audio

✓ Open

a9w3qy3j

In-viewer playback

PDF

✓ Open

ndx5vuhy

In-viewer rendering

Mixed content (born digital)

✓ Open

dn9jwck6

Multiple media types

Content advisory

⚠️ Modal

pnud3fzb

Warning modal required

Restricted whole item

🔒 Blocked

✓ Access granted

rp9jnamu

Auth + role required

Restricted audio

🔒 Blocked

✓ Access granted

esd6gs3s

Auth + role required

Restricted video

🔒 Blocked

✓ Access granted

zsgh5y3z

Auth + role required

Restricted born digital

🔒 Blocked

✓ Access granted

my6bzerr

Auth + role required

Note: The "logged in (restricted)" authentication state only affects access (whether content is granted), not which component renders — the viewer always renders regardless of auth state.

Specific Test Works

The following works provide comprehensive coverage for all scenarios from the matrix above.