Sync from GitHub · 2026-09-26 23:46 UTC

routes/bff.py

@@ -109,7 +109,7 @@ def _stage_guidance(stage: str) -> str:
     return f"\n\nBUSINESS STAGE: {label}\n{rule}"
 
 
-def _call_groq_json(system_prompt: str, user_prompt: str) -> dict:
+def _call_groq_json(system_prompt: str, user_prompt: str, fixture: str | None = None) -> dict:
     """
     Thin wrapper — delegates to the key-rotating Groq client utility.
 
@@ -118,7 +118,7 @@ def _call_groq_json(system_prompt: str, user_prompt: str) -> dict:
     reasoning before writing the final JSON — a tight budget here truncates
     the JSON output and fails to parse.
     """
-    return call_groq_json(system_prompt, user_prompt, model=HEAVY_MODEL, max_tokens=3000)
+    return call_groq_json(system_prompt, user_prompt, model=HEAVY_MODEL, max_tokens=3000, fixture=fixture)
 
 
 # ─── Route: Generate follow-up questions ─────────────────────────────────────
@@ -185,7 +185,7 @@ Question types:
 """
 
     try:
-        data = _call_groq_json(system_prompt, user_prompt)
+        data = _call_groq_json(system_prompt, user_prompt, fixture="followups")
         return data
     except Exception as e:
         raise HTTPException(status_code=500, detail=f"Follow-up generation failed: {str(e)}")
@@ -370,7 +370,7 @@ each containing a list of 2-4 concise bullet points:
         if i > 0:
             time.sleep(15)  # 15s gap: ~3,000 tokens recovered at 200 tok/s
         try:
-            results[key] = _call_groq_json(base_system, prompt_fn())
+            results[key] = _call_groq_json(base_system, prompt_fn(), fixture=key)
         except Exception as e:
             errors.append(f"{key}: {str(e)}")
             print(f"[bff] Failed to generate {key}: {e}")

routes/chat.py

@@ -113,6 +113,7 @@ RULES:
                 user_prompt=body.message,
                 model=model,
                 max_tokens=512,
+                fixture="chat_response",
             )
             for chunk in stream_response:
                 token = chunk.choices[0].delta.content

routes/consultation.py

@@ -106,7 +106,7 @@ Return JSON:
 }}"""
 
     try:
-        result = call_groq_json(system, prompt, model=HEAVY_MODEL, max_tokens=800)
+        result = call_groq_json(system, prompt, model=HEAVY_MODEL, max_tokens=800, fixture="consultation_start")
         return {
             "openingMessage": result.get("openingMessage", ""),
             "focusAreas":     result.get("focusAreas", []),
@@ -180,7 +180,7 @@ Write a formal consultation report. Return JSON:
 }}"""
 
     try:
-        result = call_groq_json(system, prompt, model=HEAVY_MODEL, max_tokens=2000)
+        result = call_groq_json(system, prompt, model=HEAVY_MODEL, max_tokens=2000, fixture="consultation_report")
         return {"report": result}
     except Exception as e:
         raise HTTPException(status_code=500, detail=f"Report generation failed: {str(e)}")

routes/documents.py

@@ -82,7 +82,7 @@ Generate a comprehensive Business Plan. Return JSON:
   "financialSummary": "Startup costs, expected revenue, break-even estimate",
   "implementationTimeline": "Key milestones for the first 12 months"
 }}"""
-    return call_groq_json(system, prompt, model=HEAVY_MODEL, max_tokens=2500)
+    return call_groq_json(system, prompt, model=HEAVY_MODEL, max_tokens=2500, fixture="business_plan")
 
 
 # ─── Pitch Deck ────────────────────────────────────────────────────────────────
@@ -130,7 +130,7 @@ Generate a 7-slide Pitch Deck. Return JSON where each key is a slide:
     "bullets": ["Seeking: ...", "Use of funds: ...", "Expected outcome: ..."]
   }}
 }}"""
-    return call_groq_json(system, prompt, model=HEAVY_MODEL, max_tokens=2000)
+    return call_groq_json(system, prompt, model=HEAVY_MODEL, max_tokens=2000, fixture="pitch_deck")
 
 
 # ─── Route ────────────────────────────────────────────────────────────────────

routes/planning.py

@@ -130,7 +130,10 @@ Return JSON:
 """
 
     try:
-        result = call_groq_json(system, prompt, model=HEAVY_MODEL, max_tokens=800)
+        result = call_groq_json(
+            system, prompt, model=HEAVY_MODEL, max_tokens=800,
+            fixture=f"planning_{body.type}",
+        )
         suggestions = result.get("suggestions", [])
         if not suggestions:
             raise ValueError("No suggestions returned")

routes/transcribe.py

@@ -51,6 +51,7 @@ async def transcribe_audio(
             file=(audio.filename or "recording.webm", audio_bytes, content_type),
             response_format="json",
             language="en",
+            fixture="transcript",
         )
         return {"transcript": transcription.text}
 

tests/fixtures/README.md

@@ -0,0 +1,9 @@
+# Test fixtures
+
+- `groq/` — canned Groq responses for `E2E_FIXTURE_MODE` (see `utils/groq_client.py`, ADR-0013).
+- `fake-service-account.json` — **not a real credential.** A throwaway RSA key generated locally
+  (`openssl genpkey`) and never registered with any Google Cloud project. It exists only so
+  `firebase_admin.credentials.Certificate()` has a syntactically valid key to parse when the
+  backend initializes against the local Firebase Emulator Suite in E2E tests
+  (`playwright.config.ts`) — the emulators never validate it against real Google infrastructure.
+  If a secret scanner flags this file: it's a known, intentional fixture, not a leaked key.

tests/fixtures/fake-service-account.json

@@ -0,0 +1,13 @@
+{
+  "type": "service_account",
+  "project_id": "venthrive-e2e-demo",
+  "private_key_id": "e2e-fake-key-id",
+  "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC47ouHuvQe0Irn\nix5oJ7DZDhfrgot0D23dYwV6cdmlpvTKyeDUWwrgHbPmTUJ5ouo3UvwG7GeiEM3t\n0cDWNL/WkeW+FS5RodY9GsfFCZJNBGUfIdjLLyWN3LMT92njkMu7pLRvuC/Cvi/i\nOKzRCwE8bY+HfDDAVCwNnacVlM6c/sHY23QJ2rKVbOcbdXa18rtSEHwHLjMfFyr/\nVokMc21dyPTyqt0QERC1qMgFoaCDj2gEHmZRq06ZqSsqJoY0hH/HvH/bqqqYzuZN\n8w8QU2Ft/4Yl3C5yPg/Hyjar/92giMf0+j9w+HxKpMK73NXLOPGEq33jkUiy0OXF\niv37vFPTAgMBAAECggEAJqpljQL3QKwcps3NFTzbOn66XJjmXGVPdL7b6d59AagX\nPYEZG31PmE1NjGTx9ams69VTcYUjI9z8mXFGLuNHiu7lSKl4DkRWnV8IjrdyGd1F\n4Uz73Xulj/Qpkw6jWpuvJTQKL+OkRMTsERIFfA2ffAlyPYMnVEclENG6GgaLboJw\nLQv56tcD+LDuqDPmP+AWKvNeLurOgS+UjcF1s7ImGJq6iA1IscuXwCFlCUHIw+yW\nTrjh1vgzra5kDM1HbFK4cc6TbQ7PFt9L9BdR4HRBKj93tG8oWT/3tggGMqmw10j+\nRCBrNp0looDXMQWk9ZPzCUzjDFeH6FWGsGkWnhNgeQKBgQDsOuMCkxec7/AasRwv\nOLJAob+frXTBkgMHASQ/smPMmvLRIOXmjPz3aosZfaE++RbfAtfgF7D9rcceAaDF\n5n5l8DJvyaMpnkTJm7KPzr96EoDau1nb0E9fxb2busbtTV74C/UmCj7dI1jdBt5S\n7SHjRBlar8lTkVI47gaOtoi4+QKBgQDIaJ5+9M5o6VXpyp6ojz8TxjYaxgJ3aIPX\nEeWo/r4g5EzudNEjtDyaIngOauDkEFg6ecjrUkrmuL9ChZpdBdvwOcXORtdKUai+\n5HdLS11zYmVFdPlV9bWJri/8bNt/P4WD7OSkF4NQ0skfupCQUKBOYEIYHn//EpPx\n7CNLFpHSKwKBgQCYPasncZx6K7fVu+aqGCPou1U/lw3z4iHJVdcCpfjjV8i9NjJz\nztEIssVKfEh6yRUQTEjLxvjtxBzbHbl7UPyMvawDlzNsEu/J7mm5fEiyZ1JbpPpY\nS3ucAVgdENY7AO3/ddVb2qaA5dLTPyXw05pPWQfuBfP9w132CpB3UPP0IQKBgQCv\nNtirwrjb/HVCrAW+9U5+qWMQUWJCp7vswxb5g48TDsc8DCH1h1UcpVo1sLfibW/V\n4DgLla0qvwdoz4pAHilGhBwu1rzPm0lfbDvoNoIDqVlFOpnrz6DiOMp3dW0Keazv\nxKO521zRwxhYhzJxGiytmXbvw2rAxatXbc8FjTv8dQKBgGf1WUk/596vqjmhGyKa\nqQuyTTGXKUCAEXduM7OedAIFoBIzHTKvFtBEDRpisDLOtwNd42RaTlgl4m5CyvJ9\nAA0aDtcPcVcVihf2QkQRy+7wb6psQMIHVL7K4MookW1Uklxy6Fdm6cQhmoWauw5n\n459M3aPoqVx/aqViD82UwLOf\n-----END PRIVATE KEY-----\n",
+  "client_email": "e2e-fake@venthrive-e2e-demo.iam.gserviceaccount.com",
+  "client_id": "000000000000000000000",
+  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+  "token_uri": "https://oauth2.googleapis.com/token",
+  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
+  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/e2e-fake%40venthrive-e2e-demo.iam.gserviceaccount.com",
+  "universe_domain": "googleapis.com"
+}

tests/fixtures/groq/businessIdentity.json

@@ -0,0 +1,10 @@
+{
+  "businessName": "Ada's Fresh Kitchen",
+  "sector": "Food & Beverage",
+  "subsector": "Meal Prep & Catering",
+  "niche": "Healthy lunch delivery for office workers",
+  "summary": "Ada's Fresh Kitchen prepares and delivers healthy, affordable lunches to office workers in Lagos who don't have time to cook. Every meal is made fresh that morning using locally sourced ingredients.",
+  "valueProposition": "Fresh, healthy lunch delivered to your desk before 12pm, every workday.",
+  "brandVoice": "warm, reliable, no-nonsense",
+  "tagline": "Fresh food, fast desk."
+}

tests/fixtures/groq/businessModel.json

@@ -0,0 +1,11 @@
+{
+  "keyPartners": ["Local vegetable and grain suppliers", "Dispatch rider network (Gokada, Max.ng)", "Office building facility managers"],
+  "keyActivities": ["Daily meal prep and cooking", "Order-taking and route planning", "Quality control and packaging"],
+  "keyResources": ["Commercial kitchen space", "Delivery riders", "Recurring customer subscription list"],
+  "valuePropositions": ["Fresh, healthy lunch delivered before 12pm", "Consistent quality and pricing", "Subscription convenience — no daily ordering hassle"],
+  "customerRelationships": ["WhatsApp broadcast list for weekly menus", "Subscription plans with loyalty discounts", "Direct feedback line for complaints"],
+  "channels": ["WhatsApp ordering", "Office cluster word-of-mouth", "Instagram for menu showcases"],
+  "customerSegments": ["Office workers in Lagos mainland business districts", "Small companies ordering team lunches"],
+  "costStructure": ["Ingredient sourcing", "Rider delivery fees", "Kitchen rent and utilities", "Packaging"],
+  "revenueStreams": ["Weekly/monthly lunch subscriptions", "One-off bulk office orders", "Corporate catering for events"]
+}

tests/fixtures/groq/business_plan.json

@@ -0,0 +1,11 @@
+{
+  "executiveSummary": "Ada's Fresh Kitchen delivers fresh, healthy lunches to office workers in Lagos who lack the time to cook and are wary of street food. By preparing meals fresh each morning and delivering directly to office clusters, the business aims to become the trusted daily lunch option for busy professionals. The goal for the next 12 months is to grow from a single-cook operation to a small team serving 300+ weekly subscribers across three office clusters.",
+  "businessOpportunity": "Office workers in Lagos mainland business districts spend significant time and money on inconsistent lunch options — either unreliable street food or slow, expensive delivery apps. There is a clear gap for a trusted, healthy, consistently-timed lunch service.",
+  "companyDescription": "Ada's Fresh Kitchen is a sole-proprietor meal-prep and delivery business based in Lagos, operating out of a small commercial kitchen and delivering via contracted riders.",
+  "targetMarket": "Office workers aged 25-40 in Ikeja, Yaba, and Maryland business districts, middle-income, health-conscious, and time-constrained.",
+  "productsServices": "Daily fresh lunch plates and weekly subscription plans, with menu rotation across 5 core meals. Pricing targets ₦1,500-₦2,500 per meal, with a subscription discount for weekly commitments.",
+  "marketingStrategy": "WhatsApp-based ordering and weekly menu broadcasts, office-cluster word-of-mouth referrals, and Instagram content showcasing daily meals.",
+  "operationsPlan": "Meals are prepared each morning in a rented commercial kitchen, packaged, and dispatched via contracted riders on fixed delivery routes timed to arrive before 12pm.",
+  "financialSummary": "Estimated startup costs of ₦800,000 (kitchen equipment, initial ingredient stock, packaging). Break-even is projected around month 5 at approximately 150 weekly subscribers.",
+  "implementationTimeline": "Month 1-2: formalize subscription plan and onboard first 50 subscribers. Month 3-6: expand to a second office cluster. Month 7-12: hire a second cook and add a third delivery route."
+}

tests/fixtures/groq/chat_response.txt

@@ -0,0 +1 @@
+That's a great question. For a lunch delivery business like yours, the fastest way to build repeat customers is a weekly subscription — it gives you predictable income and gives them one less decision to make each morning. Start with a simple 5-day plan at a slight discount versus ordering daily, and promote it directly to the office clusters you already deliver to. Track who renews each week so you know which offices are your strongest base.

tests/fixtures/groq/consultation_report.json

@@ -0,0 +1,27 @@
+{
+  "date": "September 26, 2026",
+  "sessionSummary": "We discussed customer acquisition and retention for Ada's Fresh Kitchen, focusing on how to convert one-off lunch orders into a reliable weekly subscription base.",
+  "keyFindings": [
+    "Most current orders are one-off rather than recurring, leaving revenue unpredictable week to week.",
+    "Word-of-mouth within office clusters is the strongest existing acquisition channel.",
+    "There is no simple way for customers to commit to a recurring order today."
+  ],
+  "recommendations": [
+    {
+      "action": "Launch a 5-day weekly subscription plan at a small discount versus daily ordering",
+      "rationale": "Gives Ada's Fresh Kitchen predictable weekly revenue and removes the daily ordering decision for customers",
+      "timeline": "This week"
+    },
+    {
+      "action": "Ask every satisfied customer to refer one colleague in their office",
+      "rationale": "Office clusters are already the strongest channel — formalizing referrals compounds it",
+      "timeline": "Within 30 days"
+    }
+  ],
+  "nextSteps": [
+    "Draft the subscription pricing and share it with 10 existing customers for feedback",
+    "Set up a simple WhatsApp broadcast list for weekly menu announcements",
+    "Track subscription renewal rate weekly for the first month"
+  ],
+  "closingNote": "Ada's Fresh Kitchen already has loyal customers — the subscription model just needs to make it easy for them to keep coming back."
+}

tests/fixtures/groq/consultation_start.json

@@ -0,0 +1,10 @@
+{
+  "openingMessage": "Hi! I've reviewed the Business Footing Framework profile for Ada's Fresh Kitchen — a fresh, healthy lunch delivery service for Lagos office workers. It's a solid foundation with a clear value proposition. Today, I'd like you to pick one area to dig into together:\n\n1. Strategy & Market Position\n2. Customer Acquisition & Retention\n3. Financial Planning & Pricing\n4. Operations & Standard Processes\n5. Investor Readiness & Growth\n\nWhich one would be most useful to focus on right now?",
+  "focusAreas": [
+    "Strategy & Market Position",
+    "Customer Acquisition & Retention",
+    "Financial Planning & Pricing",
+    "Operations & Standard Processes",
+    "Investor Readiness & Growth"
+  ]
+}

tests/fixtures/groq/customerProfile.json

@@ -0,0 +1,17 @@
+{
+  "demographics": {
+    "ageRange": "25-40",
+    "gender": "mixed, slightly more female",
+    "location": "Lagos mainland office districts (Ikeja, Yaba, Maryland)",
+    "incomeLevel": "middle",
+    "educationLevel": "mostly tertiary-educated professionals",
+    "employmentStatus": "full-time office employees"
+  },
+  "psychographics": {
+    "values": ["convenience", "health", "value for money", "reliability", "time"],
+    "lifestyle": "Busy weekday routine, limited time for meal prep, health-conscious but budget-aware.",
+    "painPoints": ["No time to cook during the week", "Street food feels unhealthy", "Restaurant delivery is slow and expensive"],
+    "motivations": ["Wants to eat healthy without the effort", "Values getting lunch on time so they don't lose their break", "Prefers a trustworthy, consistent vendor over trying something new every day"]
+  },
+  "buyerPersona": "Meet Amaka, a 29-year-old marketing executive in Ikeja. She's at her desk by 8am and rarely leaves for lunch. She used to grab suya from a roadside vendor but started worrying about hygiene and wants something that fits her fitness goals. She'd happily pay a bit more for a lunch she trusts, as long as it shows up on time."
+}

tests/fixtures/groq/followups.json

@@ -0,0 +1,27 @@
+{
+  "questions": [
+    {
+      "id": "q1",
+      "question": "How many meals do you currently make in a typical day?",
+      "type": "text",
+      "placeholder": "e.g. around 30 meals"
+    },
+    {
+      "id": "q2",
+      "question": "Do you deliver the food yourself, or does someone else handle delivery?",
+      "type": "select",
+      "options": ["I deliver myself", "I have a rider", "Customers pick up"]
+    },
+    {
+      "id": "q3",
+      "question": "Have you had any repeat customers who order from you every week?",
+      "type": "boolean"
+    },
+    {
+      "id": "q4",
+      "question": "What's the biggest challenge you're facing right now?",
+      "type": "text",
+      "placeholder": "e.g. finding reliable delivery riders"
+    }
+  ]
+}

tests/fixtures/groq/marketData.json

@@ -0,0 +1,20 @@
+{
+  "tam": "The Nigerian food delivery and meal-prep market is estimated at over ₦500 billion annually, driven by urban office workers.",
+  "sam": "Office-worker lunch delivery within Lagos mainland business districts — roughly ₦15 billion annually.",
+  "som": "A realistic first-year target is 200-400 regular subscribers across 2-3 office clusters, roughly ₦40-60 million in annual revenue.",
+  "swot": {
+    "strengths": ["Fresh, made-to-order meals", "Direct relationships with office clusters", "Low overhead (no dine-in space needed)"],
+    "weaknesses": ["Limited delivery radius without more riders", "Dependent on consistent ingredient sourcing", "Brand still unknown outside initial customer base"],
+    "opportunities": ["Growing health-consciousness among young professionals", "Rise of corporate wellness budgets that could subsidize lunch", "Partnerships with office building management"],
+    "threats": ["Established food delivery apps (Chowdeck, Glovo) entering the same space", "Fuel and ingredient price volatility raising delivery costs", "Traffic delays affecting on-time delivery reputation"]
+  },
+  "pestle": {
+    "political": "Lagos State's food safety regulations are becoming stricter — proactive NAFDAC-aligned hygiene practices are a differentiator.",
+    "economic": "Inflation pressures ingredient costs; subscription pricing must be revisited quarterly.",
+    "social": "Increasing dual-income households and long commutes are pushing more workers toward pre-made meals over home cooking.",
+    "technological": "WhatsApp-based ordering and mobile payments (Moniepoint, OPay) make low-tech order-taking viable without a full app.",
+    "legal": "Food handling permits and NAFDAC registration required for packaged meal sales.",
+    "environmental": "Packaging waste is a growing concern; biodegradable containers could become a selling point."
+  },
+  "competitiveLandscape": "Competes with informal roadside food vendors on price and with app-based delivery (Chowdeck, Glovo) on convenience. Differentiation comes from a curated healthy menu and direct office-cluster relationships rather than trying to out-scale the delivery apps."
+}

tests/fixtures/groq/pitch_deck.json

@@ -0,0 +1,30 @@
+{
+  "slide1_problem": {
+    "title": "The Problem",
+    "bullets": ["Office workers waste time and money on unreliable lunch options", "Street food raises hygiene concerns", "Delivery apps are slow and expensive for daily use"]
+  },
+  "slide2_solution": {
+    "title": "Our Solution",
+    "bullets": ["Fresh, healthy lunch delivered before 12pm", "Direct relationships with office clusters", "Simple WhatsApp-based subscription ordering"]
+  },
+  "slide3_market": {
+    "title": "Market Opportunity",
+    "bullets": ["TAM: ₦500B+ Nigerian food delivery market", "SAM: ₦15B Lagos office-lunch segment", "SOM: 200-400 subscribers in year one, ~₦40-60M revenue"]
+  },
+  "slide4_business_model": {
+    "title": "How We Make Money",
+    "bullets": ["Weekly/monthly subscription plans", "One-off bulk office orders", "Corporate event catering"]
+  },
+  "slide5_traction": {
+    "title": "Traction & Milestones",
+    "bullets": ["Serving 3 office buildings today", "Growing repeat-customer base via word of mouth", "Planning first formal subscription launch"]
+  },
+  "slide6_strategy": {
+    "title": "Go-To-Market Strategy",
+    "bullets": ["Expand cluster by cluster, not city-wide", "Referral incentives within existing offices", "WhatsApp and Instagram over paid ads"]
+  },
+  "slide7_ask": {
+    "title": "The Ask",
+    "bullets": ["Seeking: ₦2,000,000 working capital", "Use of funds: second kitchen hire, delivery bikes, packaging", "Expected outcome: 3 office clusters served within 12 months"]
+  }
+}

tests/fixtures/groq/planning_milestones.json

@@ -0,0 +1,9 @@
+{
+  "suggestions": [
+    {"title": "Launch first formal weekly subscription plan", "targetDate": "2026-10-26"},
+    {"title": "Reach 100 active weekly subscribers", "targetDate": "2026-11-25"},
+    {"title": "Expand delivery to a second office cluster", "targetDate": "2026-12-25"},
+    {"title": "Hire a second cook to support kitchen capacity", "targetDate": "2027-03-25"},
+    {"title": "Reach 300 active weekly subscribers across three clusters", "targetDate": "2027-09-26"}
+  ]
+}

tests/fixtures/groq/planning_tasks.json

@@ -0,0 +1,9 @@
+{
+  "suggestions": [
+    {"title": "Draft a weekly subscription pricing sheet", "description": "Gives Ada's Fresh Kitchen a concrete offer to test with existing customers this week", "column": "todo"},
+    {"title": "Call 10 regular customers to pitch the subscription plan", "description": "Direct feedback validates pricing before a wider launch", "column": "todo"},
+    {"title": "Set up a WhatsApp broadcast list for weekly menus", "description": "Low-cost channel to keep customers engaged between orders", "column": "todo"},
+    {"title": "Confirm rider availability for a second delivery route", "description": "Needed before expanding to a second office cluster", "column": "todo"},
+    {"title": "Order packaging supplies for the next two weeks", "description": "Avoids running out mid-week during a busy order period", "column": "in_progress"}
+  ]
+}

tests/fixtures/groq/transcript.json

@@ -0,0 +1,3 @@
+{
+  "text": "I make about thirty meals a day right now and I deliver most of them myself on my motorbike."
+}

tests/test_groq_fixture_mode.py

@@ -0,0 +1,58 @@
+"""
+Unit tests for the E2E fixture-mode switch in utils/groq_client.py.
+
+Scope: fixture mode is what lets the (not-yet-built) E2E/crawler suite walk
+the app without spending real Groq tokens — see docs/qa/test-strategy.md and
+the project-e2e-testing-design memory. These tests only verify the switch
+itself behaves correctly; they don't touch real Groq (ADR-0009 keeps that
+out of scope for automation).
+"""
+import importlib
+import os
+
+import pytest
+
+
+@pytest.fixture
+def fixture_mode(monkeypatch):
+    """Reloads utils.groq_client with E2E_FIXTURE_MODE=1, then reloads it back
+    off afterward so other tests aren't affected by module-level state."""
+    monkeypatch.setenv("E2E_FIXTURE_MODE", "1")
+    import utils.groq_client as gc
+    importlib.reload(gc)
+    yield gc
+    monkeypatch.delenv("E2E_FIXTURE_MODE", raising=False)
+    importlib.reload(gc)
+
+
+def test_call_groq_json_returns_fixture_without_network(fixture_mode):
+    data = fixture_mode.call_groq_json("system", "user", fixture="businessIdentity")
+    assert data["businessName"] == "Ada's Fresh Kitchen"
+
+
+def test_call_groq_json_without_fixture_key_raises(fixture_mode):
+    with pytest.raises(RuntimeError, match="no fixture key"):
+        fixture_mode.call_groq_json("system", "user")
+
+
+def test_call_groq_json_missing_fixture_file_raises(fixture_mode):
+    with pytest.raises(RuntimeError, match="no fixture file"):
+        fixture_mode.call_groq_json("system", "user", fixture="does-not-exist")
+
+
+def test_call_groq_stream_yields_chunks_shaped_like_the_real_sdk(fixture_mode):
+    chunks = list(fixture_mode.call_groq_stream("system", "user", fixture="chat_response"))
+    assert len(chunks) > 1
+    rebuilt = "".join(c.choices[0].delta.content for c in chunks)
+    assert "subscription" in rebuilt
+
+
+def test_call_groq_transcribe_returns_object_with_text(fixture_mode):
+    result = fixture_mode.call_groq_transcribe(file=("a.webm", b"", "audio/webm"), fixture="transcript")
+    assert "meals a day" in result.text
+
+
+def test_fixture_mode_is_off_by_default():
+    import utils.groq_client as gc
+    importlib.reload(gc)
+    assert gc.FIXTURE_MODE is False

utils/groq_client.py

@@ -19,8 +19,42 @@ import os
 import json
 import time
 import threading
+from pathlib import Path
+from types import SimpleNamespace
 from groq import Groq
 
+# ─── E2E fixture mode ─────────────────────────────────────────────────────────
+# When E2E_FIXTURE_MODE=1, every call below returns a canned fixture instead of
+# hitting the real Groq API — no cost, deterministic, works offline. Used by
+# the E2E/surface-discovery test suite (see docs/qa/test-strategy.md and the
+# project-e2e-testing-design memory), never by production or by the unit tests
+# in backend/tests/ (those stay pure-function tests with no I/O).
+# Each call site passes a `fixture` key identifying which canned response it
+# wants; fixture mode with no key given is a bug at the call site, not a
+# silent fallback, so it raises loudly instead of guessing.
+FIXTURE_MODE = os.environ.get("E2E_FIXTURE_MODE") == "1"
+_FIXTURES_DIR = Path(__file__).resolve().parent.parent / "tests" / "fixtures" / "groq"
+
+
+def _load_json_fixture(name: str) -> dict:
+    path = _FIXTURES_DIR / f"{name}.json"
+    if not path.exists():
+        raise RuntimeError(
+            f"[E2E_FIXTURE_MODE] no fixture file for '{name}' at {path} — "
+            "add one under backend/tests/fixtures/groq/"
+        )
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def _load_text_fixture(name: str) -> str:
+    path = _FIXTURES_DIR / f"{name}.txt"
+    if not path.exists():
+        raise RuntimeError(
+            f"[E2E_FIXTURE_MODE] no fixture file for '{name}' at {path} — "
+            "add one under backend/tests/fixtures/groq/"
+        )
+    return path.read_text(encoding="utf-8")
+
 # ─── Load all keys ────────────────────────────────────────────────────────────
 # Accepts: GROQ_API_KEY, GROQ_API_KEY_1 ... GROQ_API_KEY_N (any suffix)
 _KEYS: list[str] = []
@@ -129,6 +163,7 @@ def call_groq_transcribe(
     model: str = TRANSCRIBE_MODEL,
     response_format: str = "json",
     language: str | None = None,
+    fixture: str | None = None,
 ):
     """
     Calls Groq's Whisper transcription endpoint with the same key-rotation
@@ -136,6 +171,15 @@ def call_groq_transcribe(
 
     `file` is the (filename, bytes, content_type) tuple the Groq SDK expects.
     """
+    if FIXTURE_MODE:
+        if not fixture:
+            raise RuntimeError(
+                "[E2E_FIXTURE_MODE] call_groq_transcribe was called with no fixture key — "
+                "every call site must pass one when fixture mode is on"
+            )
+        data = _load_json_fixture(fixture)
+        return SimpleNamespace(text=data.get("text", ""))
+
     last_error: Exception | None = None
 
     for attempt in range(len(_KEYS) + 1):
@@ -170,8 +214,17 @@ def call_groq_json(
     user_prompt: str,
     model: str = HEAVY_MODEL,
     max_tokens: int = 1500,
+    fixture: str | None = None,
 ) -> dict:
     """Convenience wrapper: calls Groq in JSON mode and returns parsed dict."""
+    if FIXTURE_MODE:
+        if not fixture:
+            raise RuntimeError(
+                "[E2E_FIXTURE_MODE] call_groq_json was called with no fixture key — "
+                "every call site must pass one when fixture mode is on"
+            )
+        return _load_json_fixture(fixture)
+
     raw = call_groq(system_prompt, user_prompt, model=model,
                     json_mode=True, max_tokens=max_tokens)
     if not raw:
@@ -187,16 +240,33 @@ def call_groq_json(
         raise RuntimeError(f"Groq returned invalid JSON (likely truncated): {e}") from e
 
 
+def _fixture_stream(text: str):
+    """Yields fake chunks shaped like the Groq SDK's streaming response —
+    chunk.choices[0].delta.content — so callers don't need to know they're
+    in fixture mode."""
+    for word in text.split(" "):
+        yield SimpleNamespace(choices=[SimpleNamespace(delta=SimpleNamespace(content=word + " "))])
+
+
 def call_groq_stream(
     system_prompt: str,
     user_prompt: str,
     model: str = LIGHT_MODEL,
     max_tokens: int = 512,
+    fixture: str | None = None,
 ):
     """
     Returns a Groq streaming completion object.
     Rotates key on 429 like all other calls.
     """
+    if FIXTURE_MODE:
+        if not fixture:
+            raise RuntimeError(
+                "[E2E_FIXTURE_MODE] call_groq_stream was called with no fixture key — "
+                "every call site must pass one when fixture mode is on"
+            )
+        return _fixture_stream(_load_text_fixture(fixture))
+
     last_error: Exception | None = None
     for attempt in range(len(_KEYS) + 1):
         try: