Speakr is a personal, self-hosted web application designed for transcribing audio recordings
Python
Add Vitest setup with prompt-variable helper unit tests
Murtaza Nasirbd4b71ae1280
diff --git a/.gitignore b/.gitignoreindex e6b571ef..2017e92f 100644--- a/.gitignore+++ b/.gitignore@@ -46,3 +46,7 @@ docs/.github-deploy.yml# Documentation conversion scripts (one-time use)scripts/convert_to_mkdocs.pyunraid/++# Frontend test tooling (Vitest)+node_modules/+package-lock.jsondiff --git a/package.json b/package.jsonnew file mode 100644index 00000000..eb7d12d9--- /dev/null+++ b/package.json@@ -0,0 +1,14 @@+{+ "name": "speakr-frontend-tests",+ "version": "0.0.0",+ "private": true,+ "type": "module",+ "description": "Frontend unit tests for Speakr. Pure-helper modules in static/js/modules/utils are tested with Vitest. Vue components are still rendered server-side by Flask and Vue is loaded from CDN at runtime, so this package.json exists only to host dev-time test tooling.",+ "scripts": {+ "test": "vitest run",+ "test:watch": "vitest"+ },+ "devDependencies": {+ "vitest": "^2.1.0"+ }+}diff --git a/static/js/app.modular.js b/static/js/app.modular.jsindex 4fa73f2c..204fd5ef 100644--- a/static/js/app.modular.js+++ b/static/js/app.modular.js@@ -21,6 +21,7 @@ import { useFolders } from './modules/composables/folders.js';// Import utilitiesimport { showToast } from './modules/utils/toast.js';import { getContrastTextColor } from './modules/utils/colors.js';+import { buildVariableList } from './modules/utils/prompt-variables.js';// Number of speaker colors available in CSS (must match styles.css)const SPEAKER_COLOR_COUNT = 16;@@ -633,76 +634,22 @@ document.addEventListener('DOMContentLoaded', async () => {const isMobileScreen = computed(() => windowWidth.value < 1024);// Aggregate `{{name}}` variables across the currently selected- // tags and folder. Returns an array of unique entries in the- // order they were first seen, each with the inferred label and- // a list of contributing sources for the UI to show next to the- // input.- const _PROMPT_VAR_RE = /\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;- const _extractVariableNames = (text) => {- if (!text || typeof text !== 'string') return [];- const names = [];- for (const match of text.matchAll(_PROMPT_VAR_RE)) {- if (!names.includes(match[1])) names.push(match[1]);- }- return names;- };- const _inferVarLabel = (name) => {- if (!name) return '';- const cleaned = name.replace(/_/g, ' ').trim();- if (!cleaned) return '';- return cleaned.charAt(0).toUpperCase() + cleaned.slice(1);- };+ // tags / folder / user / admin prompt chain. The pure helpers+ // live in modules/utils/prompt-variables.js so they can be unit+ // tested with Vitest.const selectedPromptVariables = computed(() => {- const acc = new Map(); // name -> { label, sources: [{type, name}] }- const addVars = (text, sourceLabel, sourceType) => {- for (const name of _extractVariableNames(text)) {- if (!acc.has(name)) {- acc.set(name, { name, label: _inferVarLabel(name), sources: [] });- }- const entry = acc.get(name);- if (!entry.sources.find(s => s.name === sourceLabel && s.type === sourceType)) {- entry.sources.push({ type: sourceType, name: sourceLabel });- }- }- };-- // Mirror the task-side priority chain so the inputs shown match- // whichever prompt would actually be used at summarisation time:- // tags (stack, highest priority) -> folder -> user default -> admin default- // The first non-empty layer wins; lower-priority layers are not- // scanned because their prompt would not run.-- let anyTagHasPrompt = false;- if (Array.isArray(selectedTagIds.value) && Array.isArray(availableTags.value)) {- for (const id of selectedTagIds.value) {- const tag = availableTags.value.find(t => t.id === id);- if (tag && tag.custom_prompt) {- addVars(tag.custom_prompt, tag.name, 'tag');- anyTagHasPrompt = true;- }- }- }-- let folderHasPrompt = false;- if (!anyTagHasPrompt && selectedFolderId.value && Array.isArray(availableFolders.value)) {- const folder = availableFolders.value.find(f => f.id === selectedFolderId.value);- if (folder && folder.custom_prompt) {- addVars(folder.custom_prompt, folder.name, 'folder');- folderHasPrompt = true;- }- }-- let userPromptHasContent = false;- if (!anyTagHasPrompt && !folderHasPrompt && userSummaryPrompt.value) {- addVars(userSummaryPrompt.value, 'Your default prompt', 'user');- userPromptHasContent = true;- }-- if (!anyTagHasPrompt && !folderHasPrompt && !userPromptHasContent && adminDefaultSummaryPrompt.value) {- addVars(adminDefaultSummaryPrompt.value, 'Site default prompt', 'admin');- }-- return Array.from(acc.values());+ const tagsWithPrompts = (Array.isArray(selectedTagIds.value) && Array.isArray(availableTags.value))+ ? selectedTagIds.value.map(id => availableTags.value.find(t => t.id === id)).filter(Boolean)+ : [];+ const folder = (selectedFolderId.value && Array.isArray(availableFolders.value))+ ? (availableFolders.value.find(f => f.id === selectedFolderId.value) || null)+ : null;+ return buildVariableList({+ tagsWithPrompts,+ folder,+ userPrompt: userSummaryPrompt.value,+ adminPrompt: adminDefaultSummaryPrompt.value,+ });});// Same shape as selectedPromptVariables but for a recording that@@ -712,43 +659,12 @@ document.addEventListener('DOMContentLoaded', async () => {const reprocessAvailableVariables = computed(() => {if (!selectedRecording.value) return [];const recording = selectedRecording.value;- const acc = new Map();- const addVars = (text, sourceLabel, sourceType) => {- for (const name of _extractVariableNames(text)) {- if (!acc.has(name)) {- acc.set(name, { name, label: _inferVarLabel(name), sources: [] });- }- const entry = acc.get(name);- if (!entry.sources.find(s => s.name === sourceLabel && s.type === sourceType)) {- entry.sources.push({ type: sourceType, name: sourceLabel });- }- }- };-- let anyTagHasPrompt = false;- if (Array.isArray(recording.tags)) {- for (const tag of recording.tags) {- if (tag && tag.custom_prompt) {- addVars(tag.custom_prompt, tag.name, 'tag');- anyTagHasPrompt = true;- }- }- }- let folderHasPrompt = false;- if (!anyTagHasPrompt && recording.folder && recording.folder.custom_prompt) {- addVars(recording.folder.custom_prompt, recording.folder.name, 'folder');- folderHasPrompt = true;- }- let userPromptHasContent = false;- if (!anyTagHasPrompt && !folderHasPrompt && userSummaryPrompt.value) {- addVars(userSummaryPrompt.value, 'Your default prompt', 'user');- userPromptHasContent = true;- }- if (!anyTagHasPrompt && !folderHasPrompt && !userPromptHasContent && adminDefaultSummaryPrompt.value) {- addVars(adminDefaultSummaryPrompt.value, 'Site default prompt', 'admin');- }-- return Array.from(acc.values());+ return buildVariableList({+ tagsWithPrompts: Array.isArray(recording.tags) ? recording.tags : [],+ folder: recording.folder || null,+ userPrompt: userSummaryPrompt.value,+ adminPrompt: adminDefaultSummaryPrompt.value,+ });});const isMobileDevice = computed(() => {return /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent) ||diff --git a/static/js/modules/utils/prompt-variables.js b/static/js/modules/utils/prompt-variables.jsnew file mode 100644index 00000000..fef0365a--- /dev/null+++ b/static/js/modules/utils/prompt-variables.js@@ -0,0 +1,86 @@+/**+ * Prompt-template variable helpers.+ *+ * Mirrors the server-side logic in `src/utils/prompt_variables.py` so the+ * upload form and reprocess modal surface exactly the variables that the+ * summary task would substitute at run time.+ *+ * Identifier rule: ASCII letter or underscore, then letters/digits/underscores.+ * The frontend never substitutes — it only enumerates names so the user can+ * fill values. The backend does the actual substitution.+ */++export const PROMPT_VAR_RE = /\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;++export const extractVariableNames = (text) => {+ if (!text || typeof text !== 'string') return [];+ const names = [];+ for (const match of text.matchAll(PROMPT_VAR_RE)) {+ if (!names.includes(match[1])) names.push(match[1]);+ }+ return names;+};++export const inferVarLabel = (name) => {+ if (!name) return '';+ const cleaned = name.replace(/_/g, ' ').trim();+ if (!cleaned) return '';+ return cleaned.charAt(0).toUpperCase() + cleaned.slice(1);+};++/**+ * Build the variable list for a given priority chain. Returns an array of+ * `{ name, label, sources: [{ type, name }] }` in the order names are first+ * seen.+ *+ * Priority chain (matches `generate_summary_only_task`):+ * tags (any tag with a prompt wins as a layer) → folder → user default → admin default+ * Only the first non-empty layer is scanned. Lower layers are skipped because+ * their prompt would not run at summarisation time.+ *+ * `tagsWithPrompts` is `[{ name, custom_prompt }, ...]`. `folder` is+ * `{ name, custom_prompt }` or null. `userPrompt` and `adminPrompt` are+ * raw strings or null/empty.+ */+export const buildVariableList = ({ tagsWithPrompts, folder, userPrompt, adminPrompt }) => {+ const acc = new Map();+ const addVars = (text, sourceLabel, sourceType) => {+ for (const name of extractVariableNames(text)) {+ if (!acc.has(name)) {+ acc.set(name, { name, label: inferVarLabel(name), sources: [] });+ }+ const entry = acc.get(name);+ if (!entry.sources.find(s => s.name === sourceLabel && s.type === sourceType)) {+ entry.sources.push({ type: sourceType, name: sourceLabel });+ }+ }+ };++ let anyTagHasPrompt = false;+ if (Array.isArray(tagsWithPrompts)) {+ for (const tag of tagsWithPrompts) {+ if (tag && tag.custom_prompt) {+ addVars(tag.custom_prompt, tag.name, 'tag');+ anyTagHasPrompt = true;+ }+ }+ }++ let folderHasPrompt = false;+ if (!anyTagHasPrompt && folder && folder.custom_prompt) {+ addVars(folder.custom_prompt, folder.name, 'folder');+ folderHasPrompt = true;+ }++ let userPromptHasContent = false;+ if (!anyTagHasPrompt && !folderHasPrompt && userPrompt) {+ addVars(userPrompt, 'Your default prompt', 'user');+ userPromptHasContent = true;+ }++ if (!anyTagHasPrompt && !folderHasPrompt && !userPromptHasContent && adminPrompt) {+ addVars(adminPrompt, 'Site default prompt', 'admin');+ }++ return Array.from(acc.values());+};diff --git a/static/js/modules/utils/prompt-variables.test.js b/static/js/modules/utils/prompt-variables.test.jsnew file mode 100644index 00000000..daaaa10b--- /dev/null+++ b/static/js/modules/utils/prompt-variables.test.js@@ -0,0 +1,240 @@+import { describe, it, expect } from 'vitest';+import {+ PROMPT_VAR_RE,+ extractVariableNames,+ inferVarLabel,+ buildVariableList,+} from './prompt-variables.js';++describe('extractVariableNames', () => {+ it('returns an empty array for empty / non-string inputs', () => {+ expect(extractVariableNames('')).toEqual([]);+ expect(extractVariableNames(null)).toEqual([]);+ expect(extractVariableNames(undefined)).toEqual([]);+ expect(extractVariableNames(42)).toEqual([]);+ expect(extractVariableNames({})).toEqual([]);+ });++ it('extracts a single variable', () => {+ expect(extractVariableNames('Agenda: {{agenda}}')).toEqual(['agenda']);+ });++ it('extracts multiple variables in source order', () => {+ expect(extractVariableNames('{{a}} then {{b}} then {{c}}')).toEqual(['a', 'b', 'c']);+ });++ it('deduplicates repeated variables, keeping first-seen order', () => {+ expect(extractVariableNames('{{a}} {{b}} {{a}} {{c}} {{b}}')).toEqual(['a', 'b', 'c']);+ });++ it('tolerates whitespace inside the braces', () => {+ expect(extractVariableNames('{{ agenda }} {{ location }}')).toEqual(['agenda', 'location']);+ });++ it('accepts identifier-shaped names with digits and underscores', () => {+ expect(extractVariableNames('{{user_1}} {{_private}} {{a1b2}}')).toEqual(['user_1', '_private', 'a1b2']);+ });++ it('rejects identifiers that start with a digit', () => {+ expect(extractVariableNames('{{1bad}} {{2nd}}')).toEqual([]);+ });++ it('rejects identifiers with hyphens or other punctuation', () => {+ expect(extractVariableNames('{{has-hyphen}} {{has.dot}} {{has space}}')).toEqual([]);+ });++ it('rejects unicode identifiers (ASCII-only by design)', () => {+ // Documented limitation in src/utils/prompt_variables.py+ expect(extractVariableNames('{{café}} {{日本}}')).toEqual([]);+ });++ it('does not match single braces', () => {+ expect(extractVariableNames('{not_a_var} {also not}')).toEqual([]);+ });++ it('does not match unbalanced braces', () => {+ expect(extractVariableNames('{{unclosed}')).toEqual([]);+ expect(extractVariableNames('unclosed}}')).toEqual([]);+ });++ it('treats SSTI probe identifiers as plain names (no eval, no attribute access)', () => {+ // The frontend never substitutes — it just enumerates names. The+ // backend single-pass re.sub guarantees the same on the server.+ expect(extractVariableNames('{{__class__}} {{config}} {{__import__}}')).toEqual([+ '__class__', 'config', '__import__',+ ]);+ });+});++describe('inferVarLabel', () => {+ it('returns empty for empty input', () => {+ expect(inferVarLabel('')).toBe('');+ expect(inferVarLabel(null)).toBe('');+ expect(inferVarLabel(undefined)).toBe('');+ });++ it('capitalises and replaces underscores with spaces', () => {+ expect(inferVarLabel('agenda')).toBe('Agenda');+ expect(inferVarLabel('meeting_location')).toBe('Meeting location');+ expect(inferVarLabel('quarterly_review_notes')).toBe('Quarterly review notes');+ });++ it('handles single underscore and trims', () => {+ expect(inferVarLabel('_')).toBe('');+ expect(inferVarLabel('_private')).toBe('Private');+ });++ it('does not break on already-capitalised input', () => {+ expect(inferVarLabel('Agenda')).toBe('Agenda');+ });+});++describe('PROMPT_VAR_RE', () => {+ it('is global so matchAll yields every occurrence', () => {+ expect(PROMPT_VAR_RE.global).toBe(true);+ });++ it('is the same shape as the server-side pattern', () => {+ // Sanity check: server-side regex is r"\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}".+ // Identical class semantics; if these diverge, the upload form will+ // surface a different set of variables than the server substitutes.+ expect(PROMPT_VAR_RE.source).toBe('\\{\\{\\s*([A-Za-z_][A-Za-z0-9_]*)\\s*\\}\\}');+ });+});++describe('buildVariableList — priority chain', () => {+ const input = (over = {}) => ({+ tagsWithPrompts: [],+ folder: null,+ userPrompt: '',+ adminPrompt: '',+ ...over,+ });++ it('returns empty when no source has any prompt', () => {+ expect(buildVariableList(input())).toEqual([]);+ });++ it('returns empty when sources have prompts but no variables', () => {+ expect(buildVariableList(input({+ tagsWithPrompts: [{ name: 'Plain', custom_prompt: 'Just summarise.' }],+ }))).toEqual([]);+ });++ it('uses tags when at least one tag has a prompt with variables', () => {+ const result = buildVariableList(input({+ tagsWithPrompts: [{ name: 'Meeting', custom_prompt: 'Agenda: {{agenda}}' }],+ folder: { name: 'Projects', custom_prompt: '{{project}}' },+ userPrompt: 'User: {{quarter}}',+ adminPrompt: 'Admin: {{org}}',+ }));+ expect(result.map(v => v.name)).toEqual(['agenda']);+ expect(result[0].sources).toEqual([{ type: 'tag', name: 'Meeting' }]);+ });++ it('aggregates variables across multiple tags with prompts', () => {+ const result = buildVariableList(input({+ tagsWithPrompts: [+ { name: 'TagA', custom_prompt: '{{agenda}}' },+ { name: 'TagB', custom_prompt: '{{location}}' },+ { name: 'TagC', custom_prompt: 'No vars here' },+ ],+ }));+ expect(result.map(v => v.name)).toEqual(['agenda', 'location']);+ });++ it('records multiple sources for the same variable name when both tags use it', () => {+ const result = buildVariableList(input({+ tagsWithPrompts: [+ { name: 'TagA', custom_prompt: '{{agenda}}' },+ { name: 'TagB', custom_prompt: 'Also {{agenda}}' },+ ],+ }));+ expect(result).toHaveLength(1);+ expect(result[0].sources).toEqual([+ { type: 'tag', name: 'TagA' },+ { type: 'tag', name: 'TagB' },+ ]);+ });++ it('skips tags with no custom_prompt', () => {+ const result = buildVariableList(input({+ tagsWithPrompts: [+ { name: 'TagA', custom_prompt: null },+ { name: 'TagB', custom_prompt: '' },+ { name: 'TagC', custom_prompt: '{{agenda}}' },+ ],+ }));+ expect(result.map(v => v.name)).toEqual(['agenda']);+ expect(result[0].sources).toEqual([{ type: 'tag', name: 'TagC' }]);+ });++ it('falls through to folder when no tag has a prompt', () => {+ const result = buildVariableList(input({+ tagsWithPrompts: [{ name: 'Plain', custom_prompt: null }],+ folder: { name: 'Projects', custom_prompt: '{{project}}' },+ userPrompt: 'User: {{quarter}}',+ }));+ expect(result.map(v => v.name)).toEqual(['project']);+ expect(result[0].sources).toEqual([{ type: 'folder', name: 'Projects' }]);+ });++ it('skips folder layer when any tag had a prompt, even if folder has variables', () => {+ const result = buildVariableList(input({+ tagsWithPrompts: [{ name: 'TagA', custom_prompt: '{{agenda}}' }],+ folder: { name: 'F', custom_prompt: '{{project}}' },+ }));+ expect(result.map(v => v.name)).toEqual(['agenda']);+ });++ it('falls through to user prompt when no tags and no folder prompt', () => {+ const result = buildVariableList(input({+ folder: null,+ userPrompt: 'User: {{quarter}} {{agenda}}',+ adminPrompt: 'Admin: {{org}}',+ }));+ expect(result.map(v => v.name)).toEqual(['quarter', 'agenda']);+ expect(result[0].sources).toEqual([{ type: 'user', name: 'Your default prompt' }]);+ });++ it('falls through to admin prompt only when nothing above has content', () => {+ const result = buildVariableList(input({+ adminPrompt: 'Org: {{org}}',+ }));+ expect(result.map(v => v.name)).toEqual(['org']);+ expect(result[0].sources).toEqual([{ type: 'admin', name: 'Site default prompt' }]);+ });++ it('skips admin when user prompt has any content (even if it has no variables)', () => {+ const result = buildVariableList(input({+ userPrompt: 'Plain user prompt with no variables',+ adminPrompt: '{{org}}',+ }));+ // User prompt wins as a layer; admin layer is not scanned.+ expect(result).toEqual([]);+ });++ it('skips folder when folder has no custom_prompt, falls through to user', () => {+ const result = buildVariableList(input({+ folder: { name: 'Empty', custom_prompt: null },+ userPrompt: '{{quarter}}',+ }));+ expect(result.map(v => v.name)).toEqual(['quarter']);+ });++ it('handles non-array tagsWithPrompts gracefully', () => {+ expect(buildVariableList(input({ tagsWithPrompts: null, userPrompt: '{{q}}' }))+ .map(v => v.name)).toEqual(['q']);+ expect(buildVariableList(input({ tagsWithPrompts: undefined, userPrompt: '{{q}}' }))+ .map(v => v.name)).toEqual(['q']);+ });++ it('produces label and sources fields for each entry', () => {+ const result = buildVariableList(input({+ tagsWithPrompts: [{ name: 'M', custom_prompt: '{{meeting_location}}' }],+ }));+ expect(result).toEqual([+ { name: 'meeting_location', label: 'Meeting location', sources: [{ type: 'tag', name: 'M' }] },+ ]);+ });+});diff --git a/vitest.config.js b/vitest.config.jsnew file mode 100644index 00000000..94ba357f--- /dev/null+++ b/vitest.config.js@@ -0,0 +1,9 @@+import { defineConfig } from 'vitest/config';++export default defineConfig({+ test: {+ include: ['static/js/**/*.test.js'],+ environment: 'node',+ globals: false,+ },+});