Skip to content

Manuals App — Tests

This document describes the current testing approach for the Manuals app.

Overview

The Manuals app now has focused tests around:

  • permissions
  • audit logging
  • media cleanup correctness

The current test suite is intended to protect the most important app behaviors during the ongoing refactor and stabilization work.

The goal is to ensure that:

  • access control stays correct
  • audit logging remains reliable
  • nested content cleanup does not regress
  • core API flows remain safe during structural changes

Testing philosophy

The Manuals app uses a practical layered testing approach.

API-level tests

Used for:

  • permissions
  • endpoint behavior
  • audit log creation
  • request/response expectations

These tests verify the app as users and clients actually experience it.

Service-level tests

Used for:

  • media cleanup behavior
  • section JSON cleanup
  • nested content correctness where pure business logic is involved

These tests verify that lower-level logic behaves correctly without needing full API requests.

Why this split matters

Some behavior is best tested through the API:

  • permission checks
  • audit side effects
  • endpoint-specific access rules

Other behavior is best tested closer to the service layer:

  • stale media cleanup
  • JSON transformation
  • content repair logic

This keeps tests:

  • easier to understand
  • faster to run
  • more precise when failures happen

Current test areas

1. Permission tests

Permission tests verify that the new capability-based permission model works correctly.

These tests cover:

  • manuals
  • chapters
  • media
  • downloads
  • PDF export

What is tested

Read access is allowed for active org members with view capability.

Write access is limited to users with manage capability.

Download access is checked separately.

Export access is checked separately.

Non-members are denied access.

Role coverage

The current tests validate behavior across org roles such as:

  • owner
  • admin
  • manager
  • engineer
  • viewer
  • outsider / non-member

Main permission expectations

Expected behavior currently includes:

  • owner/admin/manager can manage manuals-related resources
  • engineer/viewer can read manuals-related resources
  • engineer/viewer can export manuals and download files if capability mapping allows it
  • outsiders cannot access org-scoped manuals resources

Why these tests are important

The permissions layer was introduced after the refactor, so these tests protect:

  • capability mapping correctness
  • view wiring correctness
  • org scoping correctness
  • future permission changes

2. Audit logging tests

Audit tests verify that important write operations generate audit log rows.

Covered entities

Current audit tests cover:

  • manuals
  • chapters
  • manual media

Covered actions

Current audit expectations include:

  • create
  • update
  • delete

What is verified

Audit tests check that:

  • an AuditLog entry is created
  • the correct action string is written
  • the correct actor is attached
  • the correct object id is stored
  • expected metadata appears in the changes payload

Why audit tests matter

Audit logging is now part of the operational safety of the app.

These tests protect:

  • traceability
  • accountability
  • future debugging
  • compliance-style audit needs

They also help ensure that refactors do not silently remove audit coverage.

3. Media cleanup tests

Media cleanup tests verify correctness of JSON-based inline media handling for sections.

This area was especially important because the app previously had a mismatch between:

  • legacy HTML cleanup assumptions
  • current TipTap JSON content

Covered scenarios

The current tests cover:

  • deleting referenced section media
  • deleting unreferenced section media
  • deleting non-section media

Expected behavior

The cleanup logic should ensure that:

  • deleting one referenced media item removes only its stale inline block
  • other valid inline media blocks remain untouched
  • deleting unrelated media does not unnecessarily rewrite section JSON

Why these tests matter

This protects the correctness of rich-content manuals and prevents regressions where:

  • too much content is removed
  • broken inline references remain
  • unrelated content is modified

Test structure

The Manuals app test suite is currently organized around concern-based files.

Typical structure includes:

  • permission-focused API tests
  • audit-focused API tests
  • service-focused cleanup tests

This mirrors the broader app refactor, where code is now split by responsibility.

That alignment makes the tests easier to maintain.

What is currently well covered

The app now has meaningful coverage for:

  • org-scoped permissions
  • capability-based access control
  • audit logging for major top-level entities
  • section inline media cleanup correctness

These areas give the app a much safer baseline than before.

What is not yet fully covered

Several important areas still need stronger regression coverage.

Nested chapter and item synchronization

Still needs more testing for:

  • merge vs replace flows
  • mixed content payloads
  • ordering behavior
  • nested updates involving sections, notes, step groups, and callouts

This remains one of the highest-value next test areas.

Concurrency-sensitive ordering

Still needs better protection around:

  • Chapter ordering
  • ChapterItem ordering
  • possible race conditions during concurrent updates

This is currently tracked as a known risk.

Expanded audit coverage

Audit logging is implemented for major entities, but not yet fully expanded across:

  • sections
  • callouts
  • step groups
  • reorder operations
  • bulk nested changes

This is a good next step because the audit foundation already exists.

Download behavior details

Permissions are covered, but lower-level response behavior could still be expanded for:

  • S3 redirect mode
  • local streaming mode
  • content type handling
  • missing file edge cases

PDF export robustness

Current tests focus mainly on access behavior.

Future tests may also validate:

  • successful PDF response generation
  • expected content type
  • basic response headers
  • behavior for empty or deeply nested manuals

The most useful next additions are:

1. Nested sync regression tests

Priority is high because nested write flows are complex and central to the app.

Focus areas:

  • chapter create/update with items
  • step group updates
  • merge strategy
  • replace strategy
  • callout nesting
  • section rich content updates

Priority is medium to high.

Focus areas:

  • dense ordering after update
  • duplicate order prevention
  • safe behavior during reorder-like updates

3. Expanded audit tests

Priority is medium.

Focus areas:

  • callout lifecycle
  • section changes
  • step changes
  • nested write orchestration effects

4. Download and export response tests

Priority is medium.

Focus areas:

  • header assertions
  • storage-mode differences
  • file-not-found behavior
  • PDF export response validation

Test design principles

The Manuals app tests follow a few important principles.

Keep tests focused

Each test should verify one main behavior.

That makes failures easier to understand and fix.

Prefer realistic org-scoped setups

Because the app is multi-tenant, tests should use realistic org membership and org-scoped objects.

This prevents false confidence from overly simplified setups.

Test behavior, not implementation details

Tests should focus on what the system guarantees, such as:

  • who can access what
  • what gets audited
  • what content gets cleaned up

rather than fragile internal implementation details.

Protect refactor boundaries

Because the app is actively being cleaned and reorganized, tests should protect important contracts between layers:

  • views and permissions
  • services and cleanup behavior
  • views and audit logging
  • serializers and nested payload behavior

Summary

The Manuals app now has a solid first wave of tests covering:

  • permissions
  • audit logging
  • media cleanup correctness

These tests significantly improve confidence during the ongoing refactor.

The next major opportunity is expanding coverage for:

  • nested sync behavior
  • ordering edge cases
  • expanded audit coverage
  • download/export robustness