@ultimabase/testing 0.0.0-stage → 0.1.1

package/src/test-adapter.ts

@@ -0,0 +1,68 @@
+// The adapter contract suite (D-02, D-73, D-94): what every adapter does
+// alike, checked through the kernel's public API.
+import type { Adapter } from 'ultimabase'
+import { describe } from 'vitest'
+import { aggregates } from './aggregates.ts'
+import { bulkReturns } from './bulk-returns.ts'
+import { calendarDays } from './days.ts'
+import { cases } from './cases.ts'
+import { cascades } from './cascades.ts'
+import { counts } from './counts.ts'
+import { decimals } from './decimals.ts'
+import { distincts } from './distincts.ts'
+import { feeds } from './feeds.ts'
+import { groups } from './groups.ts'
+import { jsonPaths } from './json-paths.ts'
+import { lists } from './lists.ts'
+import { nested } from './nested.ts'
+import { numbers } from './numbers.ts'
+import { projection } from './projection.ts'
+import { reads } from './reads.ts'
+import { relationFilters } from './relation-filters.ts'
+import { roundTrips } from './round-trips.ts'
+import { searches } from './searches.ts'
+import { sorts } from './sorts.ts'
+import { transactions } from './transactions.ts'
+import { virtuals } from './virtuals.ts'
+import { writes } from './writes.ts'
+
+export type Options = {
+	/** How many round trips the adapters have made so far, BEGIN and COMMIT included (D-98). */
+	readonly roundTrips: () => number
+}
+
+/**
+ * Runs the contract against the adapters `create` returns, one per test, each
+ * on an empty database.
+ */
+export function testAdapter(
+	name: string,
+	create: () => Adapter,
+	options: Options,
+): void {
+	describe(`the ${name} adapter`, () => {
+		reads(create)
+		cases(create)
+		writes(create)
+		cascades(create)
+		lists(create)
+		jsonPaths(create)
+		nested(create)
+		numbers(create)
+		bulkReturns(create)
+		decimals(create)
+		calendarDays(create)
+		counts(create)
+		relationFilters(create)
+		virtuals(create)
+		aggregates(create)
+		groups(create)
+		distincts(create)
+		sorts(create)
+		searches(create)
+		projection(create)
+		transactions(create)
+		feeds(create)
+		roundTrips(create, options.roundTrips)
+	})
+}

package/src/test-application.ts

@@ -0,0 +1,93 @@
+// An application's tests (D-130): before each test it starts as declared, on
+// a new memory() or its declared database's test tables (D-137) and a free
+// port, without info lines; after each it stops.
+import type { Adapter } from 'ultimabase'
+import { memory } from 'ultimabase'
+import type { Lifecycle } from 'ultimabase/internal'
+import { quietRuns, runningApi, scratchOf } from 'ultimabase/internal'
+import { afterEach, beforeAll, beforeEach } from 'vitest'
+
+export type TestApplication = {
+	/** The HTTP server's address during a test, such as `http://localhost:54321`. */
+	readonly url: string
+}
+
+/** Starts `run` with `PORT` set to `0`, then puts `PORT` back. */
+async function onFreePort(run: Lifecycle): Promise<void> {
+	const port = process.env['PORT']
+	process.env['PORT'] = '0'
+	try {
+		await run.start()
+	} finally {
+		if (port === undefined) delete process.env['PORT']
+		else process.env['PORT'] = port
+	}
+}
+
+function urlOf(api: unknown): string | undefined {
+	if (typeof api !== 'object' || api === null || !('url' in api)) {
+		return undefined
+	}
+	const { url } = api
+	if (typeof url !== 'function') return undefined
+	const value: unknown = Reflect.apply(url, api, [])
+	return typeof value === 'string' ? value : undefined
+}
+
+export type TestOptions = {
+	/**
+	 * `'declared'` runs the tests on the application's own database, in
+	 * tables of the file's own, instead of a new `memory()`.
+	 */
+	readonly database?: 'declared'
+}
+
+/** The declared database, which gives each test file empty tables. */
+function declared(database: Adapter): () => Adapter {
+	// A database that starts empty every time, as memory(), needs nothing.
+	if (database.migrations === undefined) return () => database
+	const scratch = scratchOf(database)
+	if (scratch === undefined) {
+		throw new TypeError(
+			"testApplication runs on the declared database when it gives a test file tables of its own, as postgres() does; this one does not: remove { database: 'declared' }.",
+		)
+	}
+	beforeAll(() => scratch().drop)
+	return () => database
+}
+
+/**
+ * Runs `app`, the value `defineApp` returned, around each test of the file
+ * that calls it.
+ */
+export function testApplication(
+	app: object,
+	options: TestOptions = {},
+): TestApplication {
+	const runs = quietRuns(app)
+	if (runs === undefined) {
+		throw new TypeError('testApplication takes the value defineApp returned.')
+	}
+	const database =
+		options.database === 'declared' ? declared(runs.declared) : memory
+	let run: Lifecycle | undefined
+	beforeEach(async () => {
+		run = runs.on(database())
+		await onFreePort(run)
+	})
+	afterEach(async () => {
+		await run?.stop()
+		run = undefined
+	})
+	return {
+		get url() {
+			const url = run === undefined ? undefined : urlOf(runningApi('http'))
+			if (url === undefined) {
+				throw new Error(
+					'url is the address of httpPlugin(), read during a test: add httpPlugin() to the application.',
+				)
+			}
+			return url
+		},
+	}
+}

package/src/transactions.ts

@@ -0,0 +1,76 @@
+// The transactions of the contract (D-73): one commit for every write, one
+// rollback for all of them, and nothing seen outside before the commit.
+import type { Adapter } from 'ultimabase'
+import { defineModel, master, transaction } from 'ultimabase'
+import { describe, expect, it } from 'vitest'
+import { started } from './suite.ts'
+
+const M = { as: master }
+
+const Account = defineModel({
+	name: 'Account',
+	fields: (f) => ({ name: f.string({ unique: true }) }),
+})
+
+const open = async (name: string) => Account.create({ data: { name } }, M)
+const names = async (): Promise<string[]> =>
+	(await Account.findMany({ orderBy: { name: 'asc' } }, M)).map(
+		(account) => account.name,
+	)
+
+export function transactions(create: () => Adapter): void {
+	describe('transactions', () => {
+		started(create, [Account])
+
+		it('commits every write together', async () => {
+			await transaction(async () => {
+				await open('bob')
+				await open('cy')
+			})
+			expect(await names()).toEqual(['bob', 'cy'])
+		})
+
+		it('reads its own writes', async () => {
+			const seen = await transaction(async () => {
+				await open('bob')
+				return names()
+			})
+			expect(seen).toEqual(['bob'])
+		})
+
+		it('rolls every write back when the callback throws', async () => {
+			await open('ann')
+			const failed = transaction(async () => {
+				await open('bob')
+				throw new Error('Stop.')
+			})
+			await expect(failed).rejects.toThrow('Stop.')
+			expect(await names()).toEqual(['ann'])
+		})
+
+		it('rolls back after a failed write, even one the callback catches', async () => {
+			const failed = transaction(async () => {
+				await open('bob')
+				await open('bob').catch(() => undefined)
+			})
+			await expect(failed).rejects.toMatchObject({ code: 'UNIQUE_VIOLATION' })
+			expect(await names()).toEqual([])
+		})
+
+		it('shows its writes to no one else before the commit', async () => {
+			const written = Promise.withResolvers<void>()
+			const resumed = Promise.withResolvers<void>()
+			const running = transaction(async () => {
+				await open('bob')
+				written.resolve()
+				await resumed.promise
+			})
+			await written.promise
+			// This read runs outside the transaction.
+			expect(await names()).toEqual([])
+			resumed.resolve()
+			await running
+			expect(await names()).toEqual(['bob'])
+		})
+	})
+}

package/src/virtuals.ts

@@ -0,0 +1,184 @@
+// Virtual fields in the contract (D-151): the adapter reads the fields a
+// virtual needs though the caller selects none of them, and the rows a
+// virtual returns are read again by id with their relations and counts.
+import type { Adapter, Identity } from 'ultimabase'
+import { allow, defineModel, master } from 'ultimabase'
+import { beforeEach, describe, expect, it } from 'vitest'
+import { started } from './suite.ts'
+
+const M: { readonly as: Identity } = { as: master }
+
+type Result<T> =
+	| { readonly value: T }
+	| { readonly issues: readonly { readonly message: string }[] }
+
+/** A Standard Schema of what `check` accepts, as zod would type it. */
+function schema<T>(check: (value: unknown) => value is T): {
+	readonly '~standard': {
+		readonly version: 1
+		readonly vendor: string
+		readonly validate: (value: unknown) => Result<T>
+		readonly types?: { readonly input: T; readonly output: T }
+	}
+} {
+	const validate = (value: unknown): Result<T> =>
+		check(value) ? { value } : { issues: [{ message: 'Invalid.' }] }
+	return { '~standard': { version: 1, vendor: 'testing', validate } }
+}
+
+const text = schema((value): value is string => typeof value === 'string')
+const width = schema((value): value is { readonly width: number } =>
+	Number.isInteger(Reflect.get(Object(value), 'width')),
+)
+const first = schema((value): value is { readonly first: number } =>
+	Number.isInteger(Reflect.get(Object(value), 'first')),
+)
+
+const Shelf = defineModel({
+	name: 'Shelf',
+	fields: (f) => ({
+		name: f.string(),
+		books: f.many(() => Book),
+		label: f.virtual(text, { needs: ['name'] }),
+		padded: f.virtual(text, { input: width, needs: ['name'] }),
+		latest: f.virtual(() => [Book], { input: first }),
+	}),
+}).with({
+	access: allow.public,
+	virtuals: {
+		label: { run: ({ record }) => record.name.toUpperCase() },
+		padded: {
+			run: ({ input, record }) => record.name.padEnd(input.width, '.'),
+		},
+		latest: {
+			runMany: async ({ input, records }) => {
+				const ids = records.map((record) => record.id)
+				const books = await Book.findMany(
+					{
+						where: { shelf: { is: { id: { in: ids } } } },
+						orderBy: { title: 'desc' },
+						include: { shelf: { select: { id: true } } },
+					},
+					M,
+				)
+				return records.map((record) =>
+					books
+						.filter((book) => book.shelf?.id === record.id)
+						.slice(0, input.first),
+				)
+			},
+		},
+	},
+})
+
+const Book = defineModel({
+	name: 'Book',
+	fields: (f) => ({
+		title: f.string(),
+		shelf: f.one(() => Shelf, { optional: true }),
+		tags: f.many(() => Tag),
+	}),
+}).with({ access: allow.public })
+
+const Tag = defineModel({
+	name: 'Tag',
+	fields: (f) => ({ name: f.string(), books: f.many(() => Book) }),
+}).with({ access: allow.public })
+
+export function virtuals(create: () => Adapter): void {
+	describe('virtual fields', () => {
+		started(create, [Shelf, Book, Tag])
+
+		beforeEach(async () => {
+			await Shelf.create(
+				{
+					data: {
+						name: 'oak',
+						books: {
+							create: [
+								{ title: 'A', tags: { create: [{ name: 'old' }] } },
+								{ title: 'B' },
+								{ title: 'C', tags: { create: [{ name: 'new' }] } },
+							],
+						},
+					},
+				},
+				M,
+			)
+			await Shelf.create({ data: { name: 'elm' } }, M)
+		})
+
+		it('reads the fields it needs, which the row leaves out', async () => {
+			const rows = await Shelf.findMany(
+				{
+					orderBy: { name: 'asc' },
+					select: { label: true, padded: { width: 5 } },
+				},
+				M,
+			)
+			expect(rows).toStrictEqual([
+				{ label: 'ELM', padded: 'elm..' },
+				{ label: 'OAK', padded: 'oak..' },
+			])
+		})
+
+		it('is in the default row without an input', async () => {
+			const row = await Shelf.findFirst({ where: { name: 'oak' } }, M)
+			expect(row?.label).toBe('OAK')
+			expect(row && 'padded' in row).toBe(false)
+		})
+
+		it('reads the rows it returns with their relations', async () => {
+			const rows = await Shelf.findMany(
+				{
+					orderBy: { name: 'asc' },
+					select: {
+						name: true,
+						latest: {
+							first: 2,
+							select: {
+								title: true,
+								shelf: { select: { label: true } },
+								tags: { select: { name: true } },
+								_count: { select: { tags: true } },
+							},
+						},
+					},
+				},
+				M,
+			)
+			expect(rows).toStrictEqual([
+				{ name: 'elm', latest: [] },
+				{
+					name: 'oak',
+					latest: [
+						{
+							title: 'C',
+							shelf: { label: 'OAK' },
+							tags: [{ name: 'new' }],
+							_count: { tags: 1 },
+						},
+						{
+							title: 'B',
+							shelf: { label: 'OAK' },
+							tags: [],
+							_count: { tags: 0 },
+						},
+					],
+				},
+			])
+		})
+
+		it('is read under an included relation', async () => {
+			const book = await Book.findFirst(
+				{
+					where: { title: 'A' },
+					include: { shelf: { include: { padded: { width: 4 } } } },
+				},
+				M,
+			)
+			expect(book?.shelf?.label).toBe('OAK')
+			expect(book?.shelf?.padded).toBe('oak.')
+		})
+	})
+}