diff --git a/client-sdk-references/flutter/unit-testing.mdx b/client-sdk-references/flutter/unit-testing.mdx new file mode 100644 index 00000000..7729ae22 --- /dev/null +++ b/client-sdk-references/flutter/unit-testing.mdx @@ -0,0 +1,76 @@ +--- +title: "Unit testing" +description: "Guidelines for unit testing with PowerSync" +--- + +For unit-testing your projects using PowerSync +(e.g. testing whether your queries run as expected) you will need the `powersync-sqlite-core` binary in your project's root directory. + +1. Download the PowerSync SQLite Binary + - Go to the PowerSync SQLite Core [Releases](https://github.com/powersync-ja/powersync-sqlite-core/releases). + - Download the binary compatible with your OS. +2. Rename the Binary + - Rename the binary by removing the architecture suffix. + - Example: powersync_x64.dll to powersync.dll + - Example: libpowersync_aarch64.dylib to libpowersync.dylib + - Example: libpowersync_x64.so to libpowersync.so +3. Place the binary in your project + - Move the renamed binary to the root directory of your project. + +This snippet below is only included as a guide to unit testing in Flutter with PowerSync. For more information refer to the [official Flutter unit testing documentation](https://docs.flutter.dev/cookbook/testing/unit/introduction). + +```dart +import 'dart:io'; +import 'package:powersync/powersync.dart'; +import 'package:path/path.dart'; + +const schema = Schema([ + Table('customers', [Column.text('name'), Column.text('email')]) +]); + +late final PowerSyncDatabase testDB; + +String getTestDatabasePath() async { + const dbFilename = 'powersync-test.db'; + final dir = Directory.current.absolute.path; + return join(dir, dbFilename); +} + +Future openTestDatabase() async { + testDB = PowerSyncDatabase( + schema: schema, + path: await getTestDatabasePath(), + logger: testLogger, + ); + + await testDB.initialize(); +} + +test('INSERT', () async { + await powersync.execute( + 'INSERT INTO customers(name, email) VALUES(?, ?)', ['John Doe', 'john@hotmail.com']); + + final results = await powersync.getAll('SELECT * FROM customers'); + + expect(results.length, 1); + expect(results, ['John Doe', 'john@hotmail.com']); +}); +``` + +#### If you have trouble with loading the extension confirm the following + +Ensure that your SQLite3 binary install on your system has extension loading enabled. You can confirm this by doing the following + +- Run `sqlite3` in your command-line interface. +- In the sqlite3 prompt run `PRAGMA compile_options;` +- Check the output for the option `ENABLE_LOAD_EXTENSION`. +- If you see `ENABLE_LOAD_EXTENSION`, it means extension loading is enabled. + +If the above steps don't work you can also confirm if extension loading is enabled by trying to load the extension in your command-line interface. + +- Run `sqlite3` in your command-line interface. +- Run `.load /path/to/file/libpowersync.dylib` (macOS) or `.load /path/to/file/libpowersync.so` (Linux) or `.load /path/to/file/powersync.dll` (Windows). +- If this runs without error, then extension loading is enabled. If it fails with an error message about extension loading being disabled, then it’s not enabled in your SQLite installation. + +If it is not enabled you will have to download a compiled SQLite binary with extension loading enabled (e.g. using homebrew) or [compile SQLite](https://www.sqlite.org/howtocompile.html) with extension loading enabled and +include it in you projects folder alongside the extension. diff --git a/mint.json b/mint.json index d76373ac..11c29a56 100644 --- a/mint.json +++ b/mint.json @@ -276,6 +276,7 @@ "client-sdk-references/flutter/flutter-web-support", "client-sdk-references/flutter/flutter-orm-support", "client-sdk-references/flutter/usage-examples", + "client-sdk-references/flutter/unit-testing", "client-sdk-references/flutter/api-reference" ] },