docs: add demo with partial coverage

Author: pashagolub

examples/demo/01_schema.sql

@@ -0,0 +1,19 @@
+-- Demo Schema: Simple Product Inventory System
+--
+-- This file sets up the products table and seeds a few rows so the
+-- functions in 02_functions.sql have data to work with.
+
+CREATE TABLE products (
+    id        SERIAL  PRIMARY KEY,
+    name      TEXT    NOT NULL,
+    price     NUMERIC NOT NULL,
+    stock_qty INT     NOT NULL DEFAULT 0,
+    category  TEXT    NOT NULL DEFAULT 'general'
+);
+
+-- Seed data: a variety of stock levels to exercise get_stock_status branches
+INSERT INTO products (name, price, stock_qty, category) VALUES
+    ('Laptop',     999.99, 25,  'electronics'),  -- in_stock
+    ('Headphones',  49.99,  8,  'electronics'),  -- low_stock
+    ('Desk Chair',  199.99, 0,  'furniture'),    -- out_of_stock
+    ('Notebook',     4.99, 200, 'stationery');   -- in_stock

examples/demo/02_functions.sql

@@ -0,0 +1,122 @@
+-- Demo Functions: Product Management
+--
+-- Three PL/pgSQL functions designed to demonstrate pgcov branch coverage.
+-- Key design: IF/ELSIF/ELSE branches use variable assignments (not RETURN)
+-- so that coverage signals are *reachable* — they fire inside the preceding
+-- branch body after the assignment, before ELSIF/ELSE takes over.
+
+-- ---------------------------------------------------------------------------
+-- add_product
+--   Validates inputs then inserts a new product row.
+--   Uses simple guard IFs — the NOTIFY fires before each IF check, so the
+--   validation guards register as covered on every successful call.
+-- ---------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION add_product(
+    p_name     TEXT,
+    p_price    NUMERIC,
+    p_stock    INT     DEFAULT 0,
+    p_category TEXT    DEFAULT 'general'
+) RETURNS INT AS $$
+DECLARE
+    v_id INT;
+BEGIN
+    IF p_name IS NULL OR p_name = '' THEN
+        RAISE EXCEPTION 'Product name cannot be empty';
+    END IF;
+
+    IF p_price < 0 THEN
+        RAISE EXCEPTION 'Price must be non-negative, got %', p_price;
+    END IF;
+
+    IF p_stock < 0 THEN
+        RAISE EXCEPTION 'Stock must be non-negative, got %', p_stock;
+    END IF;
+
+    INSERT INTO products (name, price, stock_qty, category)
+    VALUES (p_name, p_price, p_stock, p_category)
+    RETURNING id INTO v_id;
+
+    RETURN v_id;
+END;
+$$ LANGUAGE plpgsql;
+
+-- ---------------------------------------------------------------------------
+-- get_stock_status
+--   Returns a human-readable stock level for the given product.
+--   Uses a result *variable* (not RETURN inside each branch) so that the
+--   coverage signal for each ELSIF/ELSE clause fires when the *preceding*
+--   branch executes — making uncovered branches clearly visible.
+--
+--   Branch signals:
+--     'out_of_stock' signal  → only fires when stock = 0
+--     'low_stock'   signal   → only fires when 0 < stock ≤ 10
+--   (both are missed by the basic test that uses stock = 50)
+-- ---------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION get_stock_status(
+    p_product_id INT
+) RETURNS TEXT AS $$
+DECLARE
+    v_stock  INT;
+    v_result TEXT;
+BEGIN
+    SELECT stock_qty INTO v_stock
+    FROM   products
+    WHERE  id = p_product_id;
+
+    IF NOT FOUND THEN
+        RETURN 'unknown';
+    END IF;
+
+    IF v_stock = 0 THEN
+        v_result := 'out_of_stock';
+    ELSIF v_stock <= 10 THEN
+        v_result := 'low_stock';
+    ELSE
+        v_result := 'in_stock';
+    END IF;
+
+    RETURN v_result;
+END;
+$$ LANGUAGE plpgsql;
+
+-- ---------------------------------------------------------------------------
+-- apply_pricing_policy
+--   Returns the final price after applying a customer-tier discount.
+--   Uses the same result-variable pattern: each ELSIF/ELSE signal fires
+--   inside the *preceding* tier's branch, so only tiers you actually test
+--   will register as covered.
+--
+--   Branch signals:
+--     'premium'  signal  → only fires when tier = 'vip'    (initial test)
+--     'standard' signal  → only fires when tier = 'premium' (needs comment-out)
+--     'none'     signal  → only fires when tier = 'standard'(needs comment-out)
+-- ---------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION apply_pricing_policy(
+    p_product_id INT,
+    p_tier       TEXT DEFAULT 'none'
+) RETURNS NUMERIC AS $$
+DECLARE
+    v_price    NUMERIC;
+    v_discount NUMERIC;
+BEGIN
+    SELECT price INTO v_price
+    FROM   products
+    WHERE  id = p_product_id;
+
+    IF NOT FOUND THEN
+        RAISE EXCEPTION 'Product % not found', p_product_id;
+    END IF;
+
+    IF p_tier = 'vip' THEN
+        v_discount := 0.25;
+    ELSIF p_tier = 'premium' THEN
+        v_discount := 0.15;
+    ELSIF p_tier = 'standard' THEN
+        v_discount := 0.05;
+    ELSE
+        v_discount := 0.00;
+    END IF;
+
+    RETURN ROUND(v_price * (1 - v_discount), 2);
+END;
+$$ LANGUAGE plpgsql;

examples/demo/README.md

@@ -0,0 +1,77 @@
+# Demo Example: Product Inventory System
+
+This example shows **pgcov** catching uncovered branches in PL/pgSQL functions — a
+situation that happens all the time in real projects.
+
+## What's Here
+
+| File | Description |
+| ------ | ------------- |
+| `01_schema.sql` | `products` table + seed data |
+| `02_functions.sql` | Three PL/pgSQL functions with input-validation branches |
+| `demo_test.sql` | Tests — initially happy-path only, expandable to full coverage |
+
+## The Schema
+
+A simple product inventory with three management functions:
+
+```
+add_product(name, price, stock, category) → INT
+    Branches: empty name | negative price | negative stock | happy path
+
+get_stock_status(product_id) → TEXT
+    Branches: not found ('unknown') | stock = 0 ('out_of_stock')
+            | stock ≤ 10 ('low_stock') | else ('in_stock')
+
+apply_discount(product_id, discount_pct) → NUMERIC
+    Branches: discount out of range | product not found | happy path
+```
+
+## Demo Walkthrough
+
+### Step 1 — Look at the schema
+
+Browse `01_schema.sql` and `02_functions.sql`.  
+Each function has several `IF` branches. Which ones are actually exercised?
+
+### Step 2 — Run pgcov (partial coverage)
+
+```bash
+# From the repository root
+pgcov run -c "postgresql://user@host/postgres?sslmode=disable" ./examples/demo/
+pgcov report --format html -o report-partial.html
+```
+
+Open `report-partial.html`. The validation branches are highlighted — they are
+**never reached** by the basic happy-path tests.
+
+### Step 3 — Uncomment the edge-case tests
+
+In `demo_test.sql`, remove the `--` prefix from every line of the second `DO` block
+(the one that starts with `-- DO $$`).
+
+### Step 4 — Run pgcov again (full coverage)
+
+```bash
+pgcov run -c "postgresql://user@host/postgres?sslmode=disable" ./examples/demo/
+pgcov report --format html -o report-full.html
+```
+
+Open `report-full.html`. Every branch in every function is now covered.
+
+## Quick Start
+
+```bash
+# Build the tool (once)
+go build ./cmd/pgcov
+
+# --- Partial run ---
+./pgcov run -c "postgresql://pasha@127.0.0.1/postgres?sslmode=disable" ./examples/demo/
+./pgcov report --format html -o report-partial.html
+
+# Edit demo_test.sql: uncomment the second DO block
+
+# --- Full run ---
+./pgcov run -c "postgresql://pasha@127.0.0.1/postgres?sslmode=disable" ./examples/demo/
+./pgcov report --format html -o report-full.html
+```

examples/demo/demo_test.sql

@@ -0,0 +1,76 @@
+-- Demo Tests: Product Inventory System
+--
+-- Run with:
+--   pgcov run -c "postgresql://user@host/postgres?sslmode=disable" ./examples/demo/
+--
+-- STEP 1: Run as-is to observe partial coverage (~80 %).
+-- STEP 2: Uncomment the second DO block and re-run to reach 100 %.
+
+-- Basic tests: happy-path only
+--
+-- Covers:
+--   [x] add_product       - all 5 signals (guard IFs + INSERT + RETURN fire on every call)
+--   [x] get_stock_status  - SELECT, guard IF, stock-level IF block start, RETURN
+--   [ ] get_stock_status  - 'out_of_stock' and 'low_stock' branch signals NOT hit
+--   [x] apply_pricing_policy - SELECT, guard IF, tier IF block start, 'premium' signal
+--   [ ] apply_pricing_policy - 'standard' and 'none' branch signals NOT hit
+
+DO $$
+DECLARE
+    v_id    INT;
+    v_price NUMERIC;
+BEGIN
+    -- add_product: normal case
+    v_id := add_product('Keyboard', 79.99, 50, 'electronics');
+    ASSERT v_id IS NOT NULL, 'Expected a valid product ID';
+
+    -- get_stock_status: in_stock branch (stock_qty = 50)
+    ASSERT get_stock_status(v_id) = 'in_stock',
+        format('Expected in_stock, got %s', get_stock_status(v_id));
+
+    -- apply_pricing_policy: vip tier (25 % off)
+    v_price := apply_pricing_policy(v_id, 'vip');
+    ASSERT v_price < 79.99, format('Expected discounted price, got %s', v_price);
+
+    RAISE NOTICE 'Basic tests passed -- run pgcov to see which branches are not covered!';
+END $$;
+
+
+-- Branch tests: uncomment to reach 100 % coverage
+--
+-- How the signals work:
+--   In IF/ELSIF/ELSE chains with variable assignments, pgcov injects a NOTIFY
+--   *inside* each branch (after the assignment).  That NOTIFY only fires when
+--   the BRANCH ABOVE IT is taken.  So "out_of_stock" coverage signal fires only
+--   when stock = 0; "low_stock" signal fires only when 0 < stock <= 10; etc.
+
+-- DO $$
+-- DECLARE
+--     v_id    INT;
+--     v_price NUMERIC;
+-- BEGIN
+--     -- get_stock_status: triggers the 'out_of_stock' branch signal
+--     v_id := add_product('Empty Shelf', 1.00, 0);
+--     ASSERT get_stock_status(v_id) = 'out_of_stock',
+--         format('Expected out_of_stock, got %s', get_stock_status(v_id));
+--
+--     -- get_stock_status: triggers the 'low_stock' branch signal
+--     v_id := add_product('Rare Find', 1.00, 5);
+--     ASSERT get_stock_status(v_id) = 'low_stock',
+--         format('Expected low_stock, got %s', get_stock_status(v_id));
+--
+--     -- apply_pricing_policy: premium tier (15 % off)
+--     --   triggers the 'standard' ELSIF signal (fires inside the premium branch)
+--     v_id := add_product('Priced Item', 100.00, 20);
+--     v_price := apply_pricing_policy(v_id, 'premium');
+--     ASSERT v_price = 85.00,
+--         format('Expected 85.00, got %s', v_price);
+--
+--     -- apply_pricing_policy: standard tier (5 % off)
+--     --   triggers the 'none' ELSE signal (fires inside the standard branch)
+--     v_price := apply_pricing_policy(v_id, 'standard');
+--     ASSERT v_price = 95.00,
+--         format('Expected 95.00, got %s', v_price);
+--
+--     RAISE NOTICE 'All branch tests passed -- 100%% coverage achieved!';
+-- END $$;