← all skills

printable-test-qr-codes

/home/avalon/.hermes/skills/software-development/printable-test-qr-codes/SKILL.md · raw

Printable Test QR Codes

Use this when the user wants a QR code they can print or save to their phone for manually testing a deployed web app flow.

Workflow

  1. Identify the canonical live URL - Prefer a public HTTPS route on *.apps.poofc.com. - If the QR needs a specific seeded record/table/bill, trace the app's seed/reset/data creation flow first. - Verify the target route exists publicly before generating the final QR.

  2. Add/ensure deterministic test data - If the app has a seed script, add a stable slug/record there. - If the app has a dev reset endpoint, update it too so the QR can be restored after testing. - Keep the QR target stable, e.g. /t/paradiso/test-table, not a generated database ID.

  3. Generate repo-tracked print assets - Store assets under docs/test-qr/. - Generate at least:

  4. Python generation pattern

from pathlib import Path
import qrcode
from qrcode.image.svg import SvgPathImage
from PIL import Image, ImageDraw, ImageFont

repo = Path('/path/to/repo')
out = repo / 'docs' / 'test-qr'
out.mkdir(parents=True, exist_ok=True)
url = 'https://APP.apps.poofc.com/path/to/test'
base_name = 'app-test-name'

qr = qrcode.QRCode(
    version=None,
    error_correction=qrcode.constants.ERROR_CORRECT_H,
    box_size=18,
    border=4,
)
qr.add_data(url)
qr.make(fit=True)
qr_img = qr.make_image(fill_color='#111111', back_color='white').convert('RGB')
qr_img.save(out / f'{base_name}-qr.png')

svg_img = qrcode.make(url, image_factory=SvgPathImage, error_correction=qrcode.constants.ERROR_CORRECT_H)
svg_img.save(out / f'{base_name}.svg')

# 8.5x11 at 300dpi
W, H = 2550, 3300
sheet = Image.new('RGB', (W, H), 'white')
d = ImageDraw.Draw(sheet)

def font(size, bold=False):
    candidates = [
        '/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf' if bold else '/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf',
        '/usr/share/fonts/truetype/liberation2/LiberationSans-Bold.ttf' if bold else '/usr/share/fonts/truetype/liberation2/LiberationSans-Regular.ttf',
    ]
    for p in candidates:
        try:
            return ImageFont.truetype(p, size)
        except Exception:
            pass
    return ImageFont.load_default()

def center_text(text, y, size=64, bold=False, fill='#111111'):
    f = font(size, bold)
    bbox = d.textbbox((0, 0), text, font=f)
    d.text(((W - (bbox[2] - bbox[0])) // 2, y), text, font=f, fill=fill)

center_text('Test QR', 260, 108, True)
center_text('Context / Table / Flow', 405, 76)
center_text('Scan to open the live test flow', 520, 58, fill='#444444')
qr_large = qr_img.resize((1500, 1500), Image.Resampling.NEAREST)
sheet.paste(qr_large, ((W - 1500) // 2, 760))
center_text(url, 2380, 48)
center_text('Manual QA note: reset data before/after testing if needed.', 2480, 40, fill='#555555')
center_text('Print at 100% scale for best scan reliability.', 2550, 40, fill='#555555')

sheet.save(out / f'{base_name}.png', dpi=(300, 300))
sheet.save(out / f'{base_name}.pdf', 'PDF', resolution=300.0)

  1. Document in README - Add the live QR target URL. - List the checked-in asset paths. - Mention the reset/seed behavior that restores the test record.

  2. Verify - Run the app build if code changed. - Seed/reset the data in the deployed environment. - Restart the relevant PM2 process if API code changed. - Verify:

  3. Commit, push, and deliver - Commit and push repo changes. - Send the PNG and PDF back to the user as native media with MEDIA:/absolute/path.

Pitfalls