Merge pull request #57 from MaddyGuthridge/maddy-test-migrations

Add test cases for data migration

Author: MaddyGuthridge

package-lock.json

@@ -33,7 +33,8 @@
     "spinnies": "^0.5.1",
     "superstruct": "^2.0.2",
     "tippy.js": "^6.3.7",
-    "validator": "^13.12.0"
+    "validator": "^13.12.0",
+    "yauzl": "^3.2.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.11.1",
@@ -51,6 +52,7 @@
     "@types/semver": "^7.5.8",
     "@types/spinnies": "^0.5.3",
     "@types/validator": "^13.12.0",
+    "@types/yauzl": "^2.10.3",
     "asciinema-player": "github:MaddyGuthridge/asciinema-player",
     "chalk": "^5.3.0",
     "cross-fetch": "^4.0.0",

package.json

@@ -0,0 +1,55 @@
+import yauzl, { Entry } from 'yauzl';
+import fs from 'fs';
+import path from 'path';
+
+/** Wrapper around `yauzl` to keep the callback hell contained */
+export function unzip(zipFile: string, destination: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    // Yoinked from documentation
+    yauzl.open(zipFile, { lazyEntries: true }, (err, zipfile) => {
+      if (err) {
+        // TypeScript says this is an `Error` :/
+        // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
+        reject(err);
+      }
+      zipfile.readEntry();
+      zipfile.on('entry', (entry: Entry) => {
+        if (entry.fileName.endsWith('/')) {
+          // Directory file names end with '/'.
+          // Note that entries for directories themselves are optional.
+          // An entry's fileName implicitly requires its parent directories to exist.
+          zipfile.readEntry();
+        } else {
+          // file entry
+          const outputFile = path.join(destination, entry.fileName);
+          // mkdir -p {outputFile.parent}
+          fs.mkdir(path.dirname(outputFile), { recursive: true }, (err) => {
+            if (err) {
+              reject(err);
+            }
+            // Make output stream
+            // Since the `decodeStrings` option is on-by-default, there is no need to worry about
+            // maliciously-crafted `entry.fileName` values trying to escape the destination path
+            // (eg `../../escaped`).
+            const output = fs.createWriteStream(outputFile)
+            // Read file into its output location
+            zipfile.openReadStream(entry, (err, readStream) => {
+              if (err) {
+                // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
+                reject(err);
+              }
+              // No idea why this is giving a warning -- TypeScript says it returns `void`, not `any`
+              // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+              readStream.on('end', () => zipfile.readEntry());
+              readStream.pipe(output);
+            });
+          });
+        }
+      });
+      // Once the end of the stream is reached, resolve the promise.
+      zipfile.on('close', () => {
+        resolve();
+      });
+    });
+  });
+}

src/lib/server/zip.ts

@@ -0,0 +1,4 @@
+# Migrations
+
+These test cases are used to ensure that data migrations continue to work
+correctly.

tests/backend/migrations/README.md

@@ -0,0 +1,21 @@
+import api from '$endpoints';
+import { getDataDir, getPrivateDataDir } from '$lib/server/data/dataDir';
+import { unzip } from '$lib/server/zip';
+import { rimraf } from 'rimraf';
+
+/** Extract the given zip file into the data dir, then refresh the data to trigger a migration */
+export async function migrateDataFromZip(zipFile: string) {
+  await rimraf(getDataDir());
+  await unzip(zipFile, getDataDir());
+  await api().debug.dataRefresh();
+}
+
+/**
+ * Extract the given zip file into the private data dir, then refresh the data to trigger a
+ * migration.
+ */
+export async function migratePrivateDataFromZip(zipFile: string) {
+  await rimraf(getPrivateDataDir());
+  await unzip(zipFile, getPrivateDataDir());
+  await api().debug.dataRefresh();
+}

tests/backend/migrations/migration.ts

@@ -0,0 +1,23 @@
+# Migrations / v0.6.6
+
+Migration test case for `v0.6.6`.
+
+## Data
+
+Overall structure:
+
+* `group`
+    * `listed`
+    * `unlisted`
+
+Of note:
+
+* `listed` is a listed child of `group`
+* `unlisted` is not listed as a child of `group`
+* `listed` has a URL of `https://example.com`
+* `listed` and `unlisted` link to each other
+
+## Private data
+
+* Username: `maddy`
+* Password: `Maddy123#`

tests/backend/migrations/v0.6.6/README.md

@@ -0,0 +1,66 @@
+import type { ApiClient } from '$endpoints';
+import { beforeEach, describe, expect, it } from 'vitest';
+import { setup } from '../../helpers';
+import { migrateDataFromZip, migratePrivateDataFromZip } from '../migration';
+import path from 'path';
+import itemId from '$lib/itemId';
+
+let api: ApiClient;
+
+beforeEach(async () => {
+  api = (await setup()).api;
+});
+
+describe('Public data', () => {
+  beforeEach(async () => {
+    await migrateDataFromZip(path.join(__dirname, 'data.zip'));
+  });
+
+  it('Correctly creates all items', async () => {
+    await expect(api.item(itemId.ROOT).info.get()).resolves.toMatchObject({
+      children: ['group']
+    });
+
+    await expect(api.item(itemId.fromStr('/group')).info.get()).resolves.toMatchObject({
+      // Only listed child is listed
+      children: ['listed']
+    });
+
+    // Both children resolve
+    await expect(api.item(itemId.fromStr('/group/listed')).info.get()).toResolve();
+    await expect(api.item(itemId.fromStr('/group/unlisted')).info.get()).toResolve();
+  });
+
+  it('Migrates URL sections correctly', async () => {
+    await expect(api.item(itemId.fromStr('/group/listed')).info.get()).resolves.toMatchObject({
+      sections: expect.arrayContaining([
+        {
+          type: 'site',
+          url: 'https://example.com',
+          // Uses default icon and label
+          icon: null,
+          label: null,
+        },
+      ])
+    });
+  });
+
+  it('Migrates link sections correctly', async () => {
+    await expect(api.item(itemId.fromStr('/group/listed')).info.get()).resolves.toMatchObject({
+      sections: expect.arrayContaining([
+        {
+          type: 'links',
+          label: 'See also',
+          items: ['/group/unlisted'],
+          style: 'card',
+        },
+      ])
+    });
+  });
+});
+
+it('Migrates private data correctly', async () => {
+  await migratePrivateDataFromZip(path.join(__dirname, 'private_data.zip'));
+  // We can still log in
+  await expect(api.admin.auth.login('maddy', 'Maddy123#')).toResolve();
+});