Skip to content

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/.gitignore
index 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.py
unraid/
+
+# Frontend test tooling (Vitest)
+node_modules/
+package-lock.json
diff --git a/package.json b/package.json
new file mode 100644
index 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.js
index 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 utilities
import { 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.js
new file mode 100644
index 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.js
new file mode 100644
index 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.js
new file mode 100644
index 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,
+ },
+});