halkyon-days/serverpod-offline-sync
Watch
1
0
Fork
You've already forked serverpod-offline-sync
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

test: Add a DST and tests reproducing found failures (#110)

Browse source 
Co-authored-by: Marcelo Soares <marcelo.me.soares@gmail.com>
This commit is contained in:
Kasper Overgård Nielsen 2026-09-04 18:09:20 +02:00 • committed by GitHub
commit c78af247fe
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 22825 additions and 184 deletions
Download patch file Download diff file Expand all files Collapse all files

31
packages/serverpod_offline_sync/test/hlc/hlc_comparison_test.dart
View file

@ -1,14 +1,12 @@
import 'package:serverpod_offline_sync/serverpod_offline_sync.dart';
import 'package:test/test.dart';
import 'package:uuid/uuid.dart';
final _dateTime = DateTime.parse('2001-09-09T01:46:40.000Z');
final _nodeId = const Uuid().v4obj();
import 'hlc_fixtures.dart';
void main() {
group('Given two Hlcs with same dateTime, counter and nodeId when comparing ', () {
final hlc1 = Hlc(_dateTime, 17, _nodeId);
final hlc2 = Hlc(_dateTime, 17, _nodeId);
final hlc1 = Hlc(hlcTime, 17, hlcNodeId);
final hlc2 = Hlc(hlcTime, 17, hlcNodeId);
test('then they are equal.', () {
expect(hlc1, hlc2);
@ -34,10 +32,8 @@ void main() {
group(
'Given two Hlcs with same dateTime and counter and different nodeId when comparing ',
() {
final node2 = const Uuid().v4obj();
final hlc1 = Hlc(_dateTime, 17, _nodeId);
final hlc2 = Hlc(_dateTime, 17, node2);
final hlc1 = Hlc(hlcTime, 17, hlcNodeId);
final hlc2 = Hlc(hlcTime, 17, hlcSecondNodeId);
test('then they are not equal.', () {
expect(hlc1, isNot(hlc2));
@ -50,19 +46,16 @@ void main() {
);
});
test('then one is greater or less by uuid order.', () {
if (_nodeId.uuid.compareTo(node2.uuid) > 0) {
expect(hlc1 > hlc2, isTrue);
} else {
expect(hlc1 < hlc2, isTrue);
}
test('then the lower node uuid is the lesser Hlc.', () {
expect(hlc1 < hlc2, isTrue);
expect(hlc2 > hlc1, isTrue);
});
},
);
group('Given two Hlcs with same dateTime and different counter when comparing ', () {
final hlc1 = Hlc(_dateTime, 17, _nodeId);
final hlc2 = Hlc(_dateTime, 18, _nodeId);
final hlc1 = Hlc(hlcTime, 17, hlcNodeId);
final hlc2 = Hlc(hlcTime, 18, hlcNodeId);
test('then they are not equal.', () {
expect(hlc1, isNot(hlc2));
@ -95,8 +88,8 @@ void main() {
group(
'Given two Hlcs with different dateTime when comparing ',
() {
final hlc1 = Hlc(_dateTime, 0, _nodeId);
final hlc2 = Hlc(_dateTime.add(const Duration(milliseconds: 1)), 17, _nodeId);
final hlc1 = Hlc(hlcTime, 0, hlcNodeId);
final hlc2 = Hlc(hlcTime.advance(), 17, hlcNodeId);
test('then they are not equal.', () {
expect(hlc1, isNot(hlc2));

13
packages/serverpod_offline_sync/test/hlc/hlc_copy_with_test.dart
View file

@ -1,16 +1,14 @@
import 'package:serverpod_offline_sync/serverpod_offline_sync.dart';
import 'package:test/test.dart';
import 'package:uuid/uuid.dart';
final _dateTime = DateTime.parse('2001-09-09T01:46:40.000Z');
final _nodeId = const Uuid().v4obj();
import 'hlc_fixtures.dart';
void main() {
group('Given an HLC', () {
final hlc = Hlc(_dateTime, 17, _nodeId);
final hlc = Hlc(hlcTime, 17, hlcNodeId);
test('when calling copyWith with new dateTime then result has new dateTime.', () {
final newDateTime = _dateTime.add(const Duration(minutes: 1));
final newDateTime = hlcTime.add(const Duration(minutes: 1));
final newHlc = hlc.copyWith(datetime: newDateTime);
expect(newHlc.datetime, newDateTime);
@ -23,10 +21,9 @@ void main() {
});
test('when calling copyWith with new nodeId then result has new nodeId.', () {
final newNodeId = const Uuid().v4obj();
final newHlc = hlc.copyWith(nodeId: newNodeId);
final newHlc = hlc.copyWith(nodeId: hlcSecondNodeId);
expect(newHlc.nodeId, newNodeId);
expect(newHlc.nodeId, hlcSecondNodeId);
});
});
}

46
packages/serverpod_offline_sync/test/hlc/hlc_fixtures.dart Normal file
View file

@ -0,0 +1,46 @@
/// Constant fixtures for the `Hlc` tests.
///
/// Nothing here reads the wall clock or generates a random value, because both
/// make an HLC test depend on when it runs.
///
/// `Hlc.increment` and `Hlc.merge` compare against `clock.now()` and reject a
/// timestamp that drifts more than a minute from it, so a fixture built from
/// `DateTime.now()` only passes while the run is close to the moment the
/// fixture was created. On a runner that re-executes tests in the same process
/// that stops being true, since a top-level `final` is initialized once per
/// isolate and can outlive the values derived from it.
///
/// Node ids are fixed for the same reason: `Hlc.compareTo` breaks ties on the
/// node uuid, so a random id makes the expected ordering vary between runs.
library;
import 'package:clock/clock.dart';
import 'package:uuid/uuid.dart';
/// The instant the HLC tests treat as the current wall time.
final hlcTime = DateTime.parse('2001-09-09T01:46:40.000Z');
/// A node id that sorts before [hlcSecondNodeId].
final hlcNodeId = UuidValue.withValidation(
'11111111-1111-4111-8111-111111111111',
);
/// A node id that sorts after [hlcNodeId].
final hlcSecondNodeId = UuidValue.withValidation(
'22222222-2222-4222-8222-222222222222',
);
/// Runs [body] with the wall clock pinned to [wallTime].
T atWallTime<T>(DateTime wallTime, T Function() body) =>
withClock(Clock.fixed(wallTime), body);
/// Offsets for building fixtures relative to [hlcTime].
extension HlcFixtureTime on DateTime {
/// This instant one millisecond later.
DateTime advance([Duration duration = const Duration(milliseconds: 1)]) =>
add(duration);
/// This instant one millisecond earlier.
DateTime retreat([Duration duration = const Duration(milliseconds: 1)]) =>
subtract(duration);
}

42
packages/serverpod_offline_sync/test/hlc/hlc_increment_test.dart
View file

@ -1,18 +1,17 @@
import 'package:clock/clock.dart';
import 'package:serverpod_offline_sync/serverpod_offline_sync.dart';
import 'package:test/test.dart';
import 'package:uuid/uuid.dart';
final _dateTime = DateTime.parse('2001-09-09T01:46:40.000Z');
final _nodeId = const Uuid().v4obj();
import 'hlc_fixtures.dart';
/// [Hlc.increment] derives its result from `clock.now()`, so every increment
/// here runs with the wall clock pinned to an explicit instant.
void main() {
group('Given an HLC with lower canonical time than wall time', () {
final hlc = Hlc(_dateTime, 17, _nodeId);
final wallTime = _dateTime.advance();
final hlc = Hlc(hlcTime, 17, hlcNodeId);
final wallTime = hlcTime.advance();
test('when incrementing then dateTime becomes wall time and counter resets.', () {
withClock(Clock.fixed(wallTime), () {
atWallTime(wallTime, () {
final sendHlc = hlc.increment();
expect(sendHlc, isNot(hlc));
@ -24,11 +23,11 @@ void main() {
});
group('Given an HLC with equal canonical time and wall time', () {
final hlc = Hlc(_dateTime, 17, _nodeId);
final wallTime = _dateTime;
final hlc = Hlc(hlcTime, 17, hlcNodeId);
final wallTime = hlcTime;
test('when incrementing then counter increments and dateTime is unchanged.', () {
withClock(Clock.fixed(wallTime), () {
atWallTime(wallTime, () {
final sendHlc = hlc.increment();
expect(sendHlc, isNot(hlc));
@ -40,11 +39,11 @@ void main() {
});
group('Given an HLC with higher canonical time than wall time', () {
final hlc = Hlc(_dateTime, 17, _nodeId);
final wallTime = _dateTime.retreat();
final hlc = Hlc(hlcTime, 17, hlcNodeId);
final wallTime = hlcTime.retreat();
test('when incrementing then counter increments and dateTime is unchanged.', () {
withClock(Clock.fixed(wallTime), () {
atWallTime(wallTime, () {
final sendHlc = hlc.increment();
expect(sendHlc, isNot(hlc));
@ -56,29 +55,24 @@ void main() {
});
group('Given an HLC with canonical time more than one minute ahead of wall time', () {
final hlc = Hlc(_dateTime.add(const Duration(minutes: 1, seconds: 5)), 0, _nodeId);
final wallTime = _dateTime;
final hlc = Hlc(hlcTime.add(const Duration(minutes: 1, seconds: 5)), 0, hlcNodeId);
final wallTime = hlcTime;
test('when incrementing then ClockDriftException is thrown.', () {
withClock(Clock.fixed(wallTime), () {
atWallTime(wallTime, () {
expect(hlc.increment, throwsA(isA<ClockDriftException>()));
});
});
});
group('Given an HLC with counter at maximum and canonical time at wall time', () {
final hlc = Hlc(_dateTime, 0xFFFF, _nodeId);
final wallTime = _dateTime;
final hlc = Hlc(hlcTime, 0xFFFF, hlcNodeId);
final wallTime = hlcTime;
test('when incrementing at same time then OverflowException is thrown.', () {
withClock(Clock.fixed(wallTime), () {
atWallTime(wallTime, () {
expect(hlc.increment, throwsA(isA<OverflowException>()));
});
});
});
}
extension on DateTime {
DateTime advance() => add(const Duration(milliseconds: 1));
DateTime retreat() => subtract(const Duration(milliseconds: 1));
}

79
packages/serverpod_offline_sync/test/hlc/hlc_merge_test.dart
View file

@ -1,82 +1,85 @@
import 'package:clock/clock.dart';
import 'package:serverpod_offline_sync/serverpod_offline_sync.dart';
import 'package:test/test.dart';
import 'package:uuid/uuid.dart';
final _dateTime = DateTime.now().toUtc();
final _nodeId = const Uuid().v4obj();
final _nodeIdAfter = const Uuid().v4obj();
import 'hlc_fixtures.dart';
/// [Hlc.merge] compares the remote timestamp against `clock.now()`, so every
/// merge here runs with the wall clock pinned to [hlcTime]. Without that the
/// outcome depends on how far real time has drifted from the fixtures.
void main() {
group('Given local canonical Hlc and remote with higher time', () {
final canonical = Hlc(_dateTime, 17, _nodeId);
final remote = Hlc(_dateTime.advance(), 2, _nodeIdAfter);
final canonical = Hlc(hlcTime, 17, hlcNodeId);
final remote = Hlc(hlcTime.advance(), 2, hlcSecondNodeId);
test('when merging then result has remote time and counter with local nodeId.', () {
final hlc = canonical.merge(remote);
final hlc = atWallTime(hlcTime, () => canonical.merge(remote));
expect(hlc, Hlc(remote.datetime, remote.counter, canonical.nodeId));
});
});
group('Given local canonical Hlc and remote with same time but higher counter', () {
final canonical = Hlc(_dateTime, 17, _nodeId);
final remote = Hlc(_dateTime, 18, _nodeIdAfter);
final canonical = Hlc(hlcTime, 17, hlcNodeId);
final remote = Hlc(hlcTime, 18, hlcSecondNodeId);
test('when merging then result has remote counter with local nodeId.', () {
final hlc = canonical.merge(remote);
final hlc = atWallTime(hlcTime, () => canonical.merge(remote));
expect(hlc, Hlc(canonical.datetime, remote.counter, canonical.nodeId));
});
});
group('Given local canonical Hlc and remote with same time and counter', () {
final canonical = Hlc(_dateTime, 17, _nodeId);
final remote = Hlc(_dateTime, 17, _nodeIdAfter);
final canonical = Hlc(hlcTime, 17, hlcNodeId);
final remote = Hlc(hlcTime, 17, hlcSecondNodeId);
test('when merging then local is returned.', () {
final hlc = canonical.merge(remote);
final hlc = atWallTime(hlcTime, () => canonical.merge(remote));
expect(hlc, equals(canonical));
});
});
group('Given local canonical Hlc and remote with lower time', () {
final canonical = Hlc(_dateTime, 17, _nodeId);
final remote = Hlc(_dateTime.retreat(), 17, _nodeIdAfter);
final canonical = Hlc(hlcTime, 17, hlcNodeId);
final remote = Hlc(hlcTime.retreat(), 17, hlcSecondNodeId);
test('when merging then local is returned.', () {
final hlc = canonical.merge(remote);
final hlc = atWallTime(hlcTime, () => canonical.merge(remote));
expect(hlc, equals(canonical));
});
});
group('Given local canonical Hlc and remote with same nodeId and same time', () {
final canonical = Hlc(_dateTime, 17, _nodeId);
final remote = Hlc(_dateTime, 17, _nodeId);
final canonical = Hlc(hlcTime, 17, hlcNodeId);
final remote = Hlc(hlcTime, 17, hlcNodeId);
test('when merging then node id is not checked and local is returned.', () {
expect(canonical.merge(remote), canonical);
final hlc = atWallTime(hlcTime, () => canonical.merge(remote));
expect(hlc, canonical);
});
});
group('Given local canonical Hlc and remote with same nodeId and lower time', () {
final canonical = Hlc(_dateTime, 17, _nodeId);
final remote = Hlc(_dateTime.retreat(), 17, _nodeId);
final canonical = Hlc(hlcTime, 17, hlcNodeId);
final remote = Hlc(hlcTime.retreat(), 17, hlcNodeId);
test('when merging then node id is not checked and local is returned.', () {
expect(canonical.merge(remote), canonical);
final hlc = atWallTime(hlcTime, () => canonical.merge(remote));
expect(hlc, canonical);
});
});
group('Given local canonical Hlc and remote with same nodeId and higher time', () {
final canonical = Hlc(_dateTime, 17, _nodeId);
final remote = Hlc(_dateTime.advance(), 0, _nodeId);
final canonical = Hlc(hlcTime, 17, hlcNodeId);
final remote = Hlc(hlcTime.advance(), 0, hlcNodeId);
test('when merging then DuplicateNodeException is thrown.', () {
expect(
() => canonical.merge(remote),
() => atWallTime(hlcTime, () => canonical.merge(remote)),
throwsA(isA<DuplicateNodeException>()),
);
});
@ -85,29 +88,19 @@ void main() {
group(
'Given local canonical Hlc and remote with time more than one minute ahead of wall',
() {
final canonical = Hlc(_dateTime, 17, _nodeId);
final canonical = Hlc(hlcTime, 17, hlcNodeId);
final remote = Hlc(
_dateTime.advance(const Duration(minutes: 2)),
hlcTime.advance(const Duration(minutes: 2)),
17,
_nodeIdAfter,
hlcSecondNodeId,
);
test('when merging then ClockDriftException is thrown.', () {
withClock(Clock.fixed(_dateTime.advance()), () {
expect(
() => canonical.merge(remote),
throwsA(isA<ClockDriftException>()),
);
});
expect(
() => atWallTime(hlcTime, () => canonical.merge(remote)),
throwsA(isA<ClockDriftException>()),
);
});
},
);
}
extension on DateTime {
DateTime advance([Duration duration = const Duration(milliseconds: 1)]) =>
add(duration);
DateTime retreat([Duration duration = const Duration(milliseconds: 1)]) =>
subtract(duration);
}

41
packages/serverpod_offline_sync/test/hlc/hlc_serialization_test.dart
View file

@ -1,74 +1,73 @@
import 'package:serverpod_offline_sync/serverpod_offline_sync.dart';
import 'package:test/test.dart';
import 'package:uuid/uuid.dart';
const _isoTime = '2001-09-09T01:46:40.000Z';
final _dateTime = DateTime.parse(_isoTime);
final _nodeId = const Uuid().v4obj();
import 'hlc_fixtures.dart';
final _isoTime = hlcTime.toIso8601String();
void main() {
test('Given an HLC built with dateTime, counter and nodeId '
'when reading properties '
'then dateTime, counter and nodeId match.', () {
final hlc = Hlc(_dateTime, 0x17, _nodeId);
final hlc = Hlc(hlcTime, 0x17, hlcNodeId);
expect(hlc.datetime, _dateTime);
expect(hlc.datetime, hlcTime);
expect(hlc.counter, 0x17);
expect(hlc.nodeId, _nodeId);
expect(hlc.nodeId, hlcNodeId);
});
test('Given Hlc.zero '
'when building for a nodeId '
'then it equals epoch with zero counter.', () {
final zero = Hlc.zero(_nodeId);
final zero = Hlc.zero(hlcNodeId);
expect(zero.unixTimestamp, 0);
expect(zero.counter, 0);
expect(zero.nodeId, _nodeId);
expect(zero.nodeId, hlcNodeId);
});
test('Given an ISO HLC string '
'when parsing '
'then it returns the equivalent Hlc.', () {
final hlc = Hlc(_dateTime, 0x17, _nodeId);
final hlc = Hlc(hlcTime, 0x17, hlcNodeId);
expect(Hlc.parse('${_dateTime.toIso8601String()}-0017-$_nodeId'), hlc);
expect(Hlc.parse('${hlcTime.toIso8601String()}-0017-$hlcNodeId'), hlc);
});
test('Given a Unix timestamp HLC string '
'when parsing '
'then it returns the equivalent Hlc.', () {
final hlc = Hlc(_dateTime, 0x17, _nodeId);
final hlc = Hlc(hlcTime, 0x17, hlcNodeId);
expect(Hlc.parse('${_dateTime.millisecondsSinceEpoch}-0017-$_nodeId'), hlc);
expect(Hlc.parse('${hlcTime.millisecondsSinceEpoch}-0017-$hlcNodeId'), hlc);
});
test('Given legacy string with :worker suffix '
'when parsing '
'then node id is the uuid only.', () {
final hlc = Hlc.parse('$_isoTime-0017-$_nodeId:7');
expect(hlc.nodeId, _nodeId);
final hlc = Hlc.parse('$_isoTime-0017-$hlcNodeId:7');
expect(hlc.nodeId, hlcNodeId);
expect(hlc.counter, 0x17);
expect(hlc.datetime, _dateTime);
expect(hlc.datetime, hlcTime);
});
test('Given a parsed Hlc '
'when calling toString '
'then it returns the ISO HLC string.', () {
final hlc = Hlc.parse('$_isoTime-0017-$_nodeId');
final hlc = Hlc.parse('$_isoTime-0017-$hlcNodeId');
expect(hlc.toString(), '$_isoTime-0017-$_nodeId');
expect(hlc.toString(), '$_isoTime-0017-$hlcNodeId');
});
test('Given an HLC '
'when converting to JSON '
'then it returns the equivalent string.', () {
final hlc = Hlc(_dateTime, 0x17, _nodeId);
final hlc = Hlc(hlcTime, 0x17, hlcNodeId);
expect(hlc.toJson(), {
'datetime': _dateTime.toIso8601String(),
'datetime': hlcTime.toIso8601String(),
'counter': '0017',
'node': _nodeId.toString(),
'node': hlcNodeId.toString(),
});
});
}