Clipboard Sync and Clipboard History Need Different Tests

Deskferry Team — Tue, 29 Sep 2026 14:28:58 +0000

When a two-Mac clipboard workflow fails, “the clipboard didn't work” is too vague to debug. At least four things might have happened: the source app wrote the wrong representation, a sync app didn't carry the latest copy, the destination app chose an unexpected representation, or a user tried to recover an older item that was never meant to travel between devices.

The useful distinction is current-copy transport versus local history retrieval. The first moves a new clipboard event between Macs. The second lets a person find an earlier copy on one Mac. Treating them as separate behaviours makes testing and support much clearer.

Start with an event, not a screenshot

On macOS, an NSPasteboard can expose multiple data types for an item. A copied URL might be represented as text and as a URL; a rich selection might offer plain text, HTML, and RTF. Apple documents NSPasteboard.types as the union of the declared types, and recommends checking types before reading data. The changeCount value changes when pasteboard ownership changes. Neither fact alone proves that a particular receiving app will paste the representation you expected.

For a reproducible manual test, record this small event tuple:

Field	Example
Source	Mac A, browser address bar
Event	Copy a harmless, unique marker at 10:32
Intended representation	Plain text
Destination	Mac B, plain text editor
Observation	Exact marker pasted at 10:33

Use a fresh marker for each run, such as handoff-20260929-1032. A stale marker can look like a successful sync when it is actually yesterday's clipboard content. Never use a password, token, private message, or customer data as a test marker.

Four separate checks

Source copy: Paste locally on Mac A immediately. If this fails, investigate the source app before the network.
Current-copy transfer: With both Macs approved in the same active pairing group, sync enabled and the receiving peer ready, copy a fresh marker on Mac A and paste it on Mac B. Record the copy and paste times, the pasted text, and the comparison rule you actually used. A visual match alone does not establish byte equality. Reverse the direction.
Representation choice: Repeat with a URL, a rich text selection, and an image or file only if the product tier supports those formats. Compare what the destination app actually pastes, not just what its clipboard viewer displays.
History retrieval: Pause clipboard sync to isolate local retention. On Mac A, copy marker A, then B, then C. Retrieve A from Mac A's history. Repeat independently on Mac B. Do not assume one Mac's past history has been replicated to the other.

These checks identify different failure boundaries. A successful current-copy transfer says nothing about history retention. A successful history retrieval says nothing about whether a new copy crosses the LAN.

A compact failure matrix

Symptom	First useful question
Mac B pastes an old marker	Was a fresh copy observed on Mac A after pairing?
Text works, image does not	Is the format supported by the chosen plan and receiving app?
Mac A can restore an old copy; Mac B cannot	Is history local to each Mac?
Rich formatting disappears	Which pasteboard representation did the destination choose?
One direction works	Were both devices in the same active group when the reverse copy occurred?

This is a diagnostic table, not a promise that every clipboard manager supports every cell. For Deskferry specifically, the product guide describes LAN sync for new copies while each Mac keeps its own history. Its Mac clipboard sync guide explains the two-Mac pairing workflow; the separate clipboard history guide covers local retrieval. Deskferry is available on the Mac App Store for macOS 14 or later. Use the current product guides for feature and plan details.

Make the test safe enough to repeat

Choose harmless, unique markers that reveal no private data.
Keep the receiving app constant when comparing runs; different apps may prefer different pasteboard representations.
Record whether the Macs were on the same network and active pairing group.
Record the observed result, including failures and uncertainty. A preview or successful local paste is not evidence of cross-device transfer.
Clear or replace test clipboard contents when you finish, especially on a shared machine.

If you're implementing a macOS clipboard feature, Apple's NSPasteboard.changeCount and NSPasteboard.types documentation are useful starting points. The practical lesson is to test the full copy-to-paste path with controlled content, and to report transport and history as two distinct results.

Pick the next instrument for the boundary

For the source representation, the Swift metadata-only inspector lists declared types and change count without printing the copied payload. Use it with a harmless fixture; type metadata does not prove receiver delivery.
For event timing, the seven-case new-copy simulation lets you reason about readiness, pause and reconnect. Its outcomes describe a model, so keep a separate real-device observation.
For local history, use the Mac history audit worksheet to record whether an item is found, fully accessible and actually restored. Those three answers can differ.