test: add unit tests and mocked api tests

Author: Maikuh

bunfig.toml

@@ -0,0 +1,2 @@
+[test]
+preload = ["./test-setup.ts"]

package.json

@@ -4,6 +4,7 @@
 	"scripts": {
 		"dev": "bun run --watch src/index.ts",
 		"start": "bun run src/index.ts",
+		"test": "bun test",
 		"lint": "biome check",
 		"lint:fix": "biome check --write",
 		"format": "biome format --write"

src/lib/cache.test.ts

@@ -0,0 +1,118 @@
+import { beforeEach, describe, expect, test } from 'bun:test'
+import { cacheStats, clearCache, loadFromCache, makeCacheKey, saveToCache } from './cache'
+
+const baseParams = {
+	artist: 'Taylor Swift',
+	song: 'Shake It Off',
+	timestamps: false,
+	sequence: null,
+	fast: false,
+	source: null,
+}
+
+beforeEach(() => {
+	clearCache()
+})
+
+describe('makeCacheKey', () => {
+	test('same params → same key', async () => {
+		const a = await makeCacheKey(baseParams)
+		const b = await makeCacheKey(baseParams)
+		expect(a).toBe(b)
+	})
+
+	test('different artist → different key', async () => {
+		const a = await makeCacheKey(baseParams)
+		const b = await makeCacheKey({ ...baseParams, artist: 'Ed Sheeran' })
+		expect(a).not.toBe(b)
+	})
+
+	test('different song → different key', async () => {
+		const a = await makeCacheKey(baseParams)
+		const b = await makeCacheKey({ ...baseParams, song: 'Blank Space' })
+		expect(a).not.toBe(b)
+	})
+
+	test('artist case-insensitive (normalised to lower)', async () => {
+		const a = await makeCacheKey({ ...baseParams, artist: 'taylor swift' })
+		const b = await makeCacheKey({ ...baseParams, artist: 'TAYLOR SWIFT' })
+		expect(a).toBe(b)
+	})
+
+	test('timestamps flag changes key', async () => {
+		const a = await makeCacheKey({ ...baseParams, timestamps: false })
+		const b = await makeCacheKey({ ...baseParams, timestamps: true })
+		expect(a).not.toBe(b)
+	})
+
+	test('fast flag changes key', async () => {
+		const a = await makeCacheKey({ ...baseParams, fast: false })
+		const b = await makeCacheKey({ ...baseParams, fast: true })
+		expect(a).not.toBe(b)
+	})
+
+	test('returns 64-char hex SHA-256', async () => {
+		const key = await makeCacheKey(baseParams)
+		expect(key).toMatch(/^[0-9a-f]{64}$/)
+	})
+})
+
+describe('saveToCache / loadFromCache', () => {
+	test('save then load returns same value', async () => {
+		const key = await makeCacheKey(baseParams)
+		const payload = { data: { lyrics: 'test lyrics' } }
+		saveToCache(key, payload)
+		expect(loadFromCache(key)).toEqual(payload)
+	})
+
+	test('missing key returns null', async () => {
+		expect(loadFromCache('nonexistent')).toBeNull()
+	})
+
+	test('overwrite updates value', async () => {
+		const key = await makeCacheKey(baseParams)
+		saveToCache(key, { v: 1 })
+		saveToCache(key, { v: 2 })
+		expect(loadFromCache(key)).toEqual({ v: 2 })
+	})
+})
+
+describe('clearCache', () => {
+	test('returns count of removed entries', async () => {
+		const k1 = await makeCacheKey(baseParams)
+		const k2 = await makeCacheKey({ ...baseParams, artist: 'Ed Sheeran' })
+		saveToCache(k1, {})
+		saveToCache(k2, {})
+		const { removed } = clearCache()
+		expect(removed).toBe(2)
+	})
+
+	test('after clear, load returns null', async () => {
+		const key = await makeCacheKey(baseParams)
+		saveToCache(key, { data: 'x' })
+		clearCache()
+		expect(loadFromCache(key)).toBeNull()
+	})
+
+	test('empty cache removed is 0', () => {
+		const { removed } = clearCache()
+		expect(removed).toBe(0)
+	})
+})
+
+describe('cacheStats', () => {
+	test('cache_keys reflects current size', async () => {
+		expect(cacheStats().cache_keys).toBe(0)
+		const key = await makeCacheKey(baseParams)
+		saveToCache(key, {})
+		expect(cacheStats().cache_keys).toBe(1)
+	})
+
+	test('version is v2', () => {
+		expect(cacheStats().version).toBe('v2')
+	})
+
+	test('ttl_seconds is a positive number', () => {
+		expect(cacheStats().ttl_seconds).toBeGreaterThan(0)
+	})
+})

src/lib/similarity.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from 'bun:test'
+import { sequenceMatcherRatio } from './similarity'
+
+describe('sequenceMatcherRatio', () => {
+	test('both empty → 1.0', () => {
+		expect(sequenceMatcherRatio('', '')).toBe(1.0)
+	})
+
+	test('one empty → 0.0', () => {
+		expect(sequenceMatcherRatio('hello', '')).toBe(0.0)
+		expect(sequenceMatcherRatio('', 'hello')).toBe(0.0)
+	})
+
+	test('identical strings → 1.0', () => {
+		expect(sequenceMatcherRatio('hello', 'hello')).toBe(1.0)
+		expect(sequenceMatcherRatio('shake it off', 'shake it off')).toBe(1.0)
+	})
+
+	test('completely different → 0.0', () => {
+		expect(sequenceMatcherRatio('abc', 'xyz')).toBe(0.0)
+	})
+
+	test('partial overlap is between 0 and 1', () => {
+		const r = sequenceMatcherRatio('hello world', 'hello earth')
+		expect(r).toBeGreaterThan(0)
+		expect(r).toBeLessThan(1.0)
+	})
+
+	test('symmetry: f(a,b) === f(b,a)', () => {
+		expect(sequenceMatcherRatio('taylor swift', 'swift taylor')).toBe(
+			sequenceMatcherRatio('swift taylor', 'taylor swift'),
+		)
+	})
+
+	test('single char match', () => {
+		expect(sequenceMatcherRatio('a', 'a')).toBe(1.0)
+		expect(sequenceMatcherRatio('a', 'b')).toBe(0.0)
+	})
+
+	test('substring scores high', () => {
+		const r = sequenceMatcherRatio('shake', 'shake it off')
+		expect(r).toBeGreaterThan(0.5)
+	})
+})

src/lib/validator.test.ts

@@ -0,0 +1,208 @@
+import { describe, expect, test } from 'bun:test'
+import { validateLyricsMatch } from './validator'
+
+const result = (artist: string, title: string) => ({ artist, title })
+
+describe('validateLyricsMatch', () => {
+	describe('exact matches', () => {
+		test('exact artist + song → valid', () => {
+			const r = validateLyricsMatch(
+				'Taylor Swift',
+				'Shake It Off',
+				result('Taylor Swift', 'Shake It Off'),
+			)
+			expect(r.valid).toBe(true)
+			expect(r.artist_match).toBeCloseTo(1.0, 2)
+			expect(r.song_match).toBeCloseTo(1.0, 2)
+			expect(r.script_mismatch).toBe(false)
+		})
+
+		test('case insensitive match → valid', () => {
+			const r = validateLyricsMatch(
+				'taylor swift',
+				'shake it off',
+				result('TAYLOR SWIFT', 'SHAKE IT OFF'),
+			)
+			expect(r.valid).toBe(true)
+		})
+	})
+
+	describe('no-metadata fallbacks', () => {
+		test('no title in result → trusting fetcher', () => {
+			const r = validateLyricsMatch('Artist', 'Song', { artist: 'Artist' })
+			expect(r.valid).toBe(true)
+			expect(r.reason).toContain('trusting fetcher')
+		})
+
+		test('no artist metadata → song-only match', () => {
+			const r = validateLyricsMatch('Taylor Swift', 'Shake It Off', { title: 'Shake It Off' })
+			expect(r.valid).toBe(true)
+			expect(r.reason).toContain('No artist metadata')
+		})
+	})
+
+	describe('cross-script', () => {
+		// normalizeString strips non-Latin chars via /[^\w\s]/gu so Korean/Arabic title
+		// becomes empty → hits "trusting fetcher" path (valid: true, script_mismatch: false)
+		test('CJK title stripped by normalizeString → trusting fetcher fallback', () => {
+			const r = validateLyricsMatch('BTS', 'Dynamite', { artist: 'BTS', title: '다이너마이트' })
+			expect(r.valid).toBe(true)
+			expect(r.reason).toContain('trusting fetcher')
+			expect(r.script_mismatch).toBe(false)
+		})
+
+		test('same script (both Latin) → no script_mismatch', () => {
+			const r = validateLyricsMatch(
+				'Taylor Swift',
+				'Shake It Off',
+				result('Taylor Swift', 'Shake It Off'),
+			)
+			expect(r.script_mismatch).toBe(false)
+		})
+	})
+
+	describe('mismatches', () => {
+		test('wrong artist → invalid', () => {
+			const r = validateLyricsMatch(
+				'Taylor Swift',
+				'Shake It Off',
+				result('Ed Sheeran', 'Shake It Off'),
+			)
+			expect(r.valid).toBe(false)
+			expect(r.reason).toContain('artist score')
+		})
+
+		test('wrong song → invalid', () => {
+			const r = validateLyricsMatch(
+				'Taylor Swift',
+				'Shake It Off',
+				result('Taylor Swift', 'Blank Space'),
+			)
+			expect(r.valid).toBe(false)
+			expect(r.reason).toContain('song score')
+		})
+
+		test('both wrong → reason mentions both', () => {
+			const r = validateLyricsMatch(
+				'Taylor Swift',
+				'Shake It Off',
+				result('Ed Sheeran', 'Blank Space'),
+			)
+			expect(r.valid).toBe(false)
+			expect(r.reason).toContain('artist score')
+			expect(r.reason).toContain('song score')
+		})
+	})
+
+	describe('artist matching strategies', () => {
+		test('featured artist in returned song title → valid', () => {
+			const r = validateLyricsMatch('Nicki Minaj', 'Monster', {
+				artist: 'Kanye West',
+				title: 'Monster featuring Nicki Minaj',
+			})
+			expect(r.valid).toBe(true)
+		})
+
+		test('feat. in requested artist, exact match on primary → valid', () => {
+			const r = validateLyricsMatch('Kanye West feat. Jay-Z', 'Otis', result('Kanye West', 'Otis'))
+			expect(r.valid).toBe(true)
+		})
+
+		test('artist array field → valid', () => {
+			const r = validateLyricsMatch('Taylor Swift', 'Shake It Off', {
+				artists: ['Taylor Swift'],
+				title: 'Shake It Off',
+			})
+			expect(r.valid).toBe(true)
+		})
+
+		test('trackArtist field → valid', () => {
+			const r = validateLyricsMatch('Taylor Swift', 'Shake It Off', {
+				trackArtist: 'Taylor Swift',
+				trackName: 'Shake It Off',
+			})
+			expect(r.valid).toBe(true)
+		})
+	})
+
+	describe('extension suffixes', () => {
+		test('remix suffix → valid', () => {
+			const r = validateLyricsMatch(
+				'Taylor Swift',
+				'Shake It Off',
+				result('Taylor Swift', 'Shake It Off Remix'),
+			)
+			expect(r.valid).toBe(true)
+		})
+
+		test('live suffix → valid', () => {
+			const r = validateLyricsMatch('Adele', 'Hello', result('Adele', 'Hello Live'))
+			expect(r.valid).toBe(true)
+		})
+
+		test('acoustic suffix → valid', () => {
+			const r = validateLyricsMatch(
+				'Ed Sheeran',
+				'Shape of You',
+				result('Ed Sheeran', 'Shape of You Acoustic'),
+			)
+			expect(r.valid).toBe(true)
+		})
+	})
+
+	describe('adaptive threshold', () => {
+		test('lenient threshold accepts near-miss', () => {
+			const strict = validateLyricsMatch(
+				'Radiohead',
+				'Karma Police',
+				result('Radio Head', 'Karma Police'),
+				0.99,
+			)
+			const lenient = validateLyricsMatch(
+				'Radiohead',
+				'Karma Police',
+				result('Radio Head', 'Karma Police'),
+				0.5,
+			)
+			if (!strict.valid) {
+				expect(lenient.valid).toBe(true)
+			}
+		})
+
+		test('short song name uses lower adaptive threshold', () => {
+			const r = validateLyricsMatch('Jay-Z', 'Run', result('Jay-Z', 'Run'))
+			expect(r.valid).toBe(true)
+		})
+	})
+
+	describe('returned fields', () => {
+		test('returned_artists is normalized array', () => {
+			const r = validateLyricsMatch(
+				'Taylor Swift',
+				'Shake It Off',
+				result('Taylor Swift', 'Shake It Off'),
+			)
+			expect(Array.isArray(r.returned_artists)).toBe(true)
+			expect(r.returned_artists).toContain('taylor swift')
+		})
+
+		test('returned_song is normalized', () => {
+			const r = validateLyricsMatch(
+				'Taylor Swift',
+				'Shake It Off',
+				result('Taylor Swift', 'Shake It Off'),
+			)
+			expect(r.returned_song).toBe('shake it off')
+		})
+
+		test('scores are rounded to 3 decimal places', () => {
+			const r = validateLyricsMatch(
+				'Taylor Swift',
+				'Shake It Off',
+				result('Taylor Swift', 'Shake It Off'),
+			)
+			expect(r.artist_match * 1000).toBe(Math.round(r.artist_match * 1000))
+			expect(r.song_match * 1000).toBe(Math.round(r.song_match * 1000))
+		})
+	})
+})