Test devtools extension

Author: simolus3

packages/powersync/CHANGELOG.md

@@ -1,8 +1,11 @@
-## 2.1.0
+## 2.1.0 (unreleased)
+
+- Add a DevTools extension to inspect running PowerSync databases in your app.
+
+## 2.0.2
 
 - Update PowerSync SQLite core extension to version 0.4.13.
 - Fix changes in active Sync Stream subscriptions causing a reconnect delay.
-- Add a DevTools extension to inspect running PowerSync databases in your app.
 
 ## 2.0.1
 

packages/powersync/lib/src/devtools/devtools.dart

@@ -9,7 +9,8 @@ import '../database/powersync_database.dart';
 import 'extension.dart';
 
 // We want to avoid including this code for release-mode builds, since it's only
-// relevant for development tooling.
+// relevant for development tooling. This matches the definition of Flutter's
+// kReleaseMode: https://api.flutter.dev/flutter/foundation/kReleaseMode-constant.html
 const _releaseMode = bool.fromEnvironment('dart.vm.product');
 const enable = !_releaseMode;
 

packages/powersync/pubspec.yaml

@@ -48,6 +48,7 @@ dev_dependencies:
   test_descriptor: ^2.0.2
   mockito: ^5.5.0
   yaml: ^3.1.3
+  vm_service: ^15.2.0
 
 platforms:
   android:

packages/powersync/test/devtools/app.dart

@@ -0,0 +1,25 @@
+import 'dart:io';
+
+import 'package:powersync/powersync.dart';
+import 'package:path/path.dart' as p;
+
+/// An app using a PowerSync database.
+///
+/// We use this to test the VM service extension making this database available
+/// through an IPC protocol.
+void main(List<String> args) async {
+  String databasePath;
+  if (args.isEmpty) {
+    final dir = await Directory.systemTemp.createTemp('ps-dart-extension-test');
+    databasePath = p.join(dir.path, 'test.db');
+  } else {
+    databasePath = args[0];
+  }
+
+  const schema = Schema([
+    Table('users', [Column.text('name')])
+  ]);
+  final database = PowerSyncDatabase(schema: schema, path: databasePath);
+  await database.initialize();
+  print('database is running at $databasePath!');
+}

packages/powersync/test/devtools/devtools_test.dart

@@ -0,0 +1,119 @@
+import 'dart:async';
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:path/path.dart' as p;
+import 'package:powersync/src/version.dart';
+import 'package:test/test.dart';
+import 'package:vm_service/vm_service.dart';
+import 'package:vm_service/vm_service_io.dart';
+
+void main() {
+  late Process child;
+  late VmService vm;
+  late String isolateId;
+  late Directory tmpDir;
+
+  setUpAll(() async {
+    tmpDir = await Directory.systemTemp.createTemp('ps-dart-extension-test');
+
+    // Get a random unused port.
+    final socket = await ServerSocket.bind(InternetAddress.loopbackIPv4, 0);
+    final port = socket.port;
+    await socket.close();
+
+    String sdk = p.dirname(p.dirname(Platform.resolvedExecutable));
+    child = await Process.start(p.join(sdk, 'bin', 'dart'), [
+      // Don't use dart run here to avoid https://github.com/dart-lang/native/issues/2921.
+      // Build hooks would have run for the parent process anyway.
+      //'run',
+      '--enable-vm-service=$port',
+      '--disable-service-auth-codes',
+      '--enable-asserts',
+      'test/devtools/app.dart',
+      p.join(tmpDir.path, 'test.db'),
+    ]);
+
+    final vmServiceListening = Completer<void>();
+    final databaseOpened = Completer<void>();
+
+    child.stdout.map(utf8.decode).transform(const LineSplitter()).listen((
+      line,
+    ) {
+      print('[child]: $line');
+
+      if (line.startsWith('The Dart VM service is listening')) {
+        vmServiceListening.complete();
+      } else if (line.contains('database is running')) {
+        databaseOpened.complete();
+      }
+    });
+
+    await vmServiceListening.future;
+
+    vm = await vmServiceConnectUri('ws://localhost:$port/ws');
+    await databaseOpened.future;
+
+    final state = await vm.getVM();
+    isolateId = state.isolates!.firstWhere((i) => i.name == 'main').id!;
+  });
+
+  tearDownAll(() async {
+    child.kill();
+    await child.exitCode;
+    await tmpDir.delete(recursive: true);
+  });
+
+  test('can get version', () async {
+    final response = await vm.callServiceExtension('ext.powersync.version',
+        isolateId: isolateId);
+
+    expect(response.json, {'version': libraryVersion});
+  });
+
+  test('can run queries', () async {
+    final response = await vm.callServiceExtension(
+      'ext.powersync.database',
+      args: {
+        'command': 'select',
+        'db': '0',
+        'sql': 'SELECT ?',
+        'params': '[123]',
+      },
+      isolateId: isolateId,
+    );
+    expect(response.json, {
+      'ok': {
+        'columnNames': ['?'],
+        'rows': [
+          [123]
+        ]
+      }
+    });
+  });
+
+  test('can get schema', () async {
+    final response = await vm.callServiceExtension(
+      'ext.powersync.database',
+      args: {'command': 'schema', 'db': '0'},
+      isolateId: isolateId,
+    );
+    expect(response.json, {
+      'ok': {
+        'raw_tables': <Object?>[],
+        'tables': [containsPair('name', 'users')]
+      }
+    });
+  });
+
+  test('can get sync status', () async {
+    final response = await vm.callServiceExtension(
+      'ext.powersync.database',
+      args: {'command': 'status-listen', 'db': '0'},
+      isolateId: isolateId,
+    );
+
+    expect(response.json,
+        {'ok': containsPair('current', containsPair('connected', false))});
+  });
+}

packages/powersync_devtools_extension/lib/state/databases.dart

@@ -9,11 +9,24 @@ import 'remote_database.dart';
 import 'service.dart';
 
 final class DatabaseReference {
+  /// The id of the database object generated by the `powersync` package.
   final int id;
+
+  /// A short name identifying the database.
+  ///
+  /// This is usually the last component of [path].
   final String name;
+
+  /// The path of the database.
   final String path;
+
+  /// The last credentials a connector on this database has returned.
+  ///
+  /// We use this to show credentials in the DevTools extension and to deeplink
+  /// into the diagnostics app.
   final PowerSyncCredentials? lastCredentials;
 
+  /// The isolate on which the database object has been opened.
   final IsolateRef isolate;
 
   DatabaseReference({
@@ -25,6 +38,7 @@ final class DatabaseReference {
   });
 }
 
+/// Rebuilds whenever the app opens or closes a PowerSync database.
 final _databaseListChanged = StreamProvider.autoDispose<void>((ref) {
   return Stream.fromFuture(ref.watch(serviceProvider.future)).asyncExpand(
     (serviceProvider) => serviceProvider.onExtensionEvent.where((event) {
@@ -33,6 +47,7 @@ final _databaseListChanged = StreamProvider.autoDispose<void>((ref) {
   );
 });
 
+/// An auto-updating list of currently opened PowerSync databases in the app.
 final databaseList = FutureProvider.autoDispose<List<DatabaseReference>>((
   ref,
 ) async {
@@ -84,6 +99,8 @@ final selectedDatabase =
             controller.state = null;
           } else if (controller.state == null &&
               databases.every((e) => e.id != controller.state?.ref.id)) {
+            // Auto-select the first available database once one becomes
+            // available.
             controller.state = RemoteDatabase(databases.first, service);
           }
         }, fireImmediately: true);

packages/powersync_devtools_extension/lib/ui/overview.dart

@@ -221,7 +221,7 @@ final class _SyncIssues extends ConsumerWidget {
     } else if (waitingForCheckpoint.value == true) {
       trackIssue(
         Text(
-          'Waiting for a write checkpoint containing previous uploads. If this status persist, new data would not be synced.',
+          'Waiting for a write checkpoint containing previous uploads. If this status persists, new data would not be synced.',
         ),
       );
     }
@@ -233,7 +233,7 @@ final class _SyncIssues extends ConsumerWidget {
         crossAxisAlignment: .stretch,
         children: [
           Text(
-            'The issues might affect PowerSync in your app',
+            'These issues might affect PowerSync in your app',
             style: TextTheme.of(context).bodyLarge,
           ),
           Padding(

pubspec.lock

@@ -1761,10 +1761,10 @@ packages:
     dependency: transitive
     description:
       name: vm_service
-      sha256: "046d3928e16fa4dc46e8350415661755ab759d9fc97fc21b5ab295f71e4f0499"
+      sha256: "0016aef94fc66495ac78af5859181e3f3bf2026bd8eecc72b9565601e19ab360"
       url: "https://pub.dev"
     source: hosted
-    version: "15.1.0"
+    version: "15.2.0"
   watcher:
     dependency: transitive
     description: