DEV Community: Ahsan Ahmad

Setting up Playwright with Django: a real end-to-end tutorial

Ahsan Ahmad — Tue, 13 Oct 2026 07:37:08 +0000

In Part 1 I argued that Django's test client can return a perfect 200 while the rendered page is quietly broken — because it never runs the JavaScript. Playwright is how you close that gap: it drives a real browser against your real app.

This post is the hands-on setup. By the end you'll have Playwright running against a live Django instance, logging in once instead of on every test, using selectors that don't rot, and running green in CI. Every snippet here is real, runnable code — I drive VanillaPM (a large Django app, 2,200+ tests) with Playwright daily, and this is the setup I'd hand any Django team.

We'll go in order: install → the live-server problem → your first real test → logging in once → durable selectors → debugging → CI → the gotchas that cost me hours.

1. Install

Two layers, and people forget the second one. First the Python package, then the actual browser binaries:

pip install pytest-playwright      # the Python API + pytest fixtures
playwright install chromium        # downloads the Chromium binary (~150MB)

pip install gives you the library; playwright install downloads the browser Playwright drives. On a fresh CI runner you also need the system libraries — more on that in §7.

Put both in your dev requirements so the team and CI stay in sync:

# requirements-dev.txt
pytest-playwright==0.5.2
pytest-django==4.9.0

2. The one thing that trips everyone up: a live server

Your normal Django tests call views in-process through the test client. Playwright can't use that — it's a real browser, it needs a real URL to navigate to. So you need Django to actually serve your app during the test.

Django ships exactly this: StaticLiveServerTestCase. It starts a real HTTP server on a background thread and serves your static files (plain LiveServerTestCase doesn't serve static files — use the Static one or your CSS/JS 404s and half your selectors break).

Here's the subtle part that explains a whole class of "why can't the browser see my data" bugs: LiveServerTestCase is built on TransactionTestCase, not TestCase. A normal TestCase wraps each test in a transaction and rolls it back — fast, but the data is never committed. The live server runs on a different thread with its own DB connection, so it would never see uncommitted rows. TransactionTestCase commits (and truncates tables between tests instead), which is slower but is the only way the browser-facing server can see the objects you create in the test. Keep that in mind — it's the root of the #1 gotcha in §8.

3. Your first real test

Two ways to wire this up. I'll show both because teams split on pytest vs Django's unittest.

Django's native way (`unittest` + raw Playwright)

# tests/test_e2e.py
from django.contrib.staticfiles.testing import StaticLiveServerTestCase
from playwright.sync_api import sync_playwright, expect


class HomepageTests(StaticLiveServerTestCase):
    @classmethod
    def setUpClass(cls):
        super().setUpClass()
        cls.playwright = sync_playwright().start()
        cls.browser = cls.playwright.chromium.launch()

    @classmethod
    def tearDownClass(cls):
        cls.browser.close()
        cls.playwright.stop()
        super().tearDownClass()

    def test_homepage_shows_the_hero(self):
        page = self.browser.new_page()
        page.goto(f"{self.live_server_url}/")
        expect(page.get_by_role("heading", name="Welcome")).to_be_visible()
        page.close()

self.live_server_url is handed to you by LiveServerTestCase — it's the real http://localhost:<random-port> the server is on. Run it with python manage.py test.

The pytest way (`pytest-playwright` + `pytest-django`)

This is what I'd pick for a real suite — you get the page fixture, --headed, --browser firefox, and automatic screenshots-on-failure for free:

# tests/test_e2e.py
import pytest
from playwright.sync_api import Page, expect


@pytest.mark.django_db(transaction=True)      # note: transaction=True — see below
def test_homepage_shows_the_hero(live_server, page: Page):
    page.goto(live_server.url)
    expect(page.get_by_role("heading", name="Welcome")).to_be_visible()

live_server (from pytest-django) is the fixture equivalent of StaticLiveServerTestCase; page (from pytest-playwright) is a fresh browser page per test.

The transaction=True is not optional here. Plain @pytest.mark.django_db wraps the test in a rolled-back transaction — and, exactly as in §2, the live server's thread won't see that uncommitted data. The moment a test creates something the browser needs to see (a user, a project, a row), pair live_server with transaction=True (or the transactional_db fixture). Forget it and you'll chase a phantom "the page says 0 results but I just created three."

Notice there are no sleep() calls and no manual waits. expect(locator).to_be_visible() is a web-first assertion: it polls and retries for a few seconds until the condition holds (or fails the test). This auto-waiting is most of what makes Playwright stable where Selenium was flaky — lean on it, never on time.sleep.

4. Log in once, not on every test

Logging in through the UI in every test is the single biggest waste of time in an E2E suite — a 400ms form round-trip × 80 tests is real minutes, every run. Two ways to fix it.

Option A — log in through the real UI

A small fixture that drives the actual login form. Use it in one test to prove login itself works:

# conftest.py
import pytest

@pytest.fixture
def ui_login(live_server, page):
    def _login(email, password):
        page.goto(f"{live_server.url}/accounts/login/")
        page.get_by_label("Email").fill(email)
        page.get_by_label("Password").fill(password)
        page.get_by_role("button", name="Log in").click()
        page.wait_for_url(lambda u: "/login" not in u)   # wait for the redirect
    return _login

(If you want to reuse an authenticated session across runs, save context.storage_state(path="auth.json") after logging in and pass storage_state="auth.json" to a new context. One caveat worth knowing: live_server's port changes between runs, so cookies pinned to a URL won't carry over unless you fix the port — which is exactly why, for in-suite reuse, I reach for Option B instead.)

Option B — skip the UI entirely (fastest)

Most tests don't need to re-test login — they need to be logged in. Django's test Client.force_login() mints a real session; grab its cookie and inject it straight into the browser context:

# conftest.py
import pytest
from django.conf import settings
from django.test import Client

@pytest.fixture
def login(live_server, context):
    """Return a helper that logs a given user into the browser context — no UI."""
    def _login(user):
        client = Client()
        client.force_login(user)                       # creates the session server-side
        cookie = client.cookies[settings.SESSION_COOKIE_NAME]
        context.add_cookies([{
            "name": settings.SESSION_COOKIE_NAME,
            "value": cookie.value,
            "url": live_server.url,
        }])
    return _login

@pytest.mark.django_db(transaction=True)
def test_dashboard_lists_my_projects(live_server, page, login, django_user_model):
    user = django_user_model.objects.create_user(email="a@b.com", password="x")
    # ... create a couple of projects owned by `user` ...
    login(user)
    page.goto(f"{live_server.url}/dashboard/")
    expect(page.get_by_role("link", name="Coral Ridge Resort")).to_be_visible()

force_login is the same mechanism Django's own auth uses, so the session is genuinely valid — the browser sends the sessionid, the live server reads it (committed, because transaction=True), and you're authenticated without rendering a single login form. Rule of thumb: one test that logs in through the UI (Option A) to prove login works; every other test uses Option B.

5. Selectors that survive a refactor

Brittle selectors are why people abandon E2E suites — a designer renames a class and 40 tests go red. The fix is to select the way a user finds things, not the way the DOM is nested. Playwright's locators are built for this, in rough order of preference:

page.get_by_role("button", name="Submit")      # best — role + accessible name
page.get_by_label("Email")                       # form fields by their <label>
page.get_by_text("Ready for approval")           # visible copy
page.get_by_placeholder("Search projects…")
page.get_by_test_id("project-row")               # the escape hatch: data-testid

Reserve raw CSS/XPath (page.locator(".pce-sec-head > div:nth-child(2)")) for when nothing else works — it's the first thing to break. For the genuinely hard cases, add a stable data-testid to the template and select on that; it's an explicit contract with your tests that a restyle won't void.

A concrete before/after from my own code:

# ❌ brittle — tied to layout and order
page.locator("div.toolbar > button:nth-of-type(3)").click()

# ✅ durable — tied to meaning
page.get_by_role("button", name="Save").click()

And always assert with the web-first expect, which retries, rather than reading state once:

# ❌ reads once, races the UI
assert page.locator("#status").inner_text() == "Approved"

# ✅ retries until true (or fails)
expect(page.get_by_test_id("status")).to_have_text("Approved")

6. Debugging: the tools that save the afternoon

When a test fails and you can't see why, you have better options than print-debugging:

pytest --headed --slowmo 400          # watch it run, slowed down
PWDEBUG=1 pytest -k test_dashboard     # open Playwright Inspector — step through, pick selectors
playwright codegen http://localhost:8000   # RECORD a session → it writes the selector code for you

playwright codegen is the quiet superpower for Django devs: open your running app, click through the flow by hand, and Playwright prints working locator code you paste into a test. And for the failures that only happen in CI, turn on tracing and replay them frame by frame:

pytest --tracing retain-on-failure      # pytest-playwright writes a trace.zip on failures
playwright show-trace test-results/.../trace.zip   # a full timeline: DOM snapshots, network, console

The trace viewer is the difference between "it's flaky on CI, no idea why" and watching the exact moment it went wrong, with the DOM state at every step.

7. Running it in CI (GitHub Actions)

Three CI-specific things matter: install the system libraries the browser needs (--with-deps), give Django a real database (a Postgres service), and keep these slow tests on their own job so they don't gate every unit-test run.

# .github/workflows/e2e.yml
name: e2e
on: [push, pull_request]

jobs:
  e2e:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: test_db
        ports: ["5432:5432"]
        options: >-
          --health-cmd pg_isready --health-interval 10s
          --health-timeout 5s --health-retries 5
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install -r requirements-dev.txt
      - run: playwright install --with-deps chromium    # --with-deps = the system libs
      - run: pytest -m e2e --tracing retain-on-failure
        env:
          DATABASE_URL: postgres://postgres:postgres@localhost:5432/test_db
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: playwright-traces
          path: test-results/

--with-deps is the line people miss — on a bare Ubuntu runner Chromium won't launch without a set of shared libraries, and this installs them. Uploading the traces on failure means a red CI run hands you a replayable recording, not just a stack trace. (Mark your browser tests with @pytest.mark.e2e and register the marker in pytest.ini so pytest -m e2e picks exactly them.)

8. The gotchas that cost me hours

"The browser sees 0 rows but I created 3." The transactional-DB issue from §2/§3. Use @pytest.mark.django_db(transaction=True) (or transactional_db) with live_server. This is #1 by a distance.
Static files 404 / unstyled page / missing selectors. You used LiveServerTestCase instead of StaticLiveServerTestCase, or you're testing against runserver with DEBUG=False and no collectstatic. Serve the statics.
sync_playwright + async errors ("It looks like you are using Playwright Sync API inside the asyncio loop"). Something in your stack is running an event loop. Keep the sync API out of async contexts, or switch to the async API throughout.
Flakiness from manual waits. Every time.sleep(2) is a future flake. Delete them and trust expect(...) auto-waiting and page.wait_for_url / wait_for_load_state.
Slow suite. E2E is slow by nature — keep it small (see below), reuse auth (§4), run it as its own CI job, and run the fast unit tests on every push.

What to test with this (and what not to)

Resist testing everything through the browser — a huge E2E suite is slow and flaky and the team learns to ignore it. Keep the base of your pyramid wide with fast unit tests (VanillaPM has 2,200+ of those), and spend Playwright on a small set of critical journeys: can a user log in, can they complete the one flow that must never break, does the JavaScript-heavy screen actually render. Reach for the browser only when the thing you need to verify only exists in the browser.

That's the whole setup — live server, auth reuse, durable selectors, debugging, CI, and the traps. It's the foundation the next two posts build on: Part 3 uses this same machinery to automate a couple hundred product screenshots, and Part 4 turns Playwright into a debugging instrument to hunt a CSS bug that had no visible element.

I'm building *VanillaPM** — a free, full-lifecycle PM platform — in Django, in the open. The rest of this Playwright for Django series is here if build-in-public engineering is your thing.*

Your issue tracker is not an issue log

Ahsan Ahmad — Wed, 07 Oct 2026 19:09:56 +0000

I spent years as a developer with a tidy issue tracker and a recurring, stupid problem: the things that actually derailed our projects were almost never in it.

The database migration that needed a DBA who was on leave. The client contact who stopped replying for three weeks. The staging environment nobody owned. None of these were tickets. All of them cost us more than any bug we shipped.

I only got a clean vocabulary for this when I started studying project management properly. The distinction turns out to be small, old, and genuinely useful — so I want to hand it over without the certification padding.

The distinction: an issue is not a risk

Here is the whole thing:

A risk is a problem that might happen. Future, probabilistic.
An issue is a problem that is happening. Present, certain.
When a risk materialises, it stops being a risk and becomes an issue.

That last line is the useful part. Risks are not a list you write once at kickoff and never revisit — they are supposed to graduate. "The lift supplier might get held up at customs" is a risk. The morning the lifts are actually sitting in a customs warehouse, it is an issue, and it needs a different response: not monitoring, but an owner and an action today.

Most teams I have seen have no mechanism for that transition. The risk list lives in a document from month one. The issue nobody saw coming lands in standup as a surprise. It was not a surprise — it was on page two.

Why your tracker can't hold this

Nothing stops you putting "lifts stuck at customs" in Jira. People do. It is just that the tracker is already doing a different job, and the two jobs fight.

Your tracker holds work you intend to do. Issues are problems blocking work you already planned. Mixed into one backlog:

The blocker gets a priority label and sits in a column with forty other things.
It has an assignee — but the assignee is usually whoever will do the work after the blocker clears, not the person who can clear it. Those are frequently different people, and often the blocker-clearer is not an engineer at all.
It has no escalation path. A ticket's escalation is "move it up the backlog". A real blocker's escalation is "this needs the sponsor to make a call by Thursday".
It closes when the code merges. But most impediments are cleared by a conversation, a decision, or a payment — nothing merges, so nothing closes.

The mismatch is not about tooling. It is that one of these is a work queue and the other is a blocker list, and a blocker list is read by different people, at a different cadence, with different authority to act.

RAID, in ninety seconds

The frame this comes from is RAID — four registers, kept separately because they get different treatment:

	What it is	What you do with it
Risks	Might happen	Monitor; plan a response in advance
Assumptions	Believed true, unverified	Validate before it bites you
Issues	Happening now	Own it, date it, drive it closed
Dependencies	Someone else's work gates yours	Track the other party, not your own team

It looks like bureaucracy. In practice, for a team of any size, it is four lists and a weekly ten minutes. The value is almost entirely in the separation — assumptions in particular, because an unexamined assumption is the single most common way a plan quietly becomes wrong.

What actually changes in practice

Four things, and they are cheap:

One named owner per issue — a person, not a team. "Platform team" owns nothing. Unowned issues drift, and drift is the default state of a blocker that is inconvenient for everyone.

A date, not a priority. Priorities inflate until everything is P1. A date is falsifiable: Thursday arrives and either it moved or it did not.

An explicit escalation path. Before you need it. "If this is not cleared by Thursday, it goes to X." Most blockers persist not because they are hard but because nobody knew who was allowed to decide.

Review and close, in a fixed cadence. The failure mode of every issue log is becoming a graveyard — forty open entries, half resolved months ago, nobody trusting it enough to read it. A log nobody trusts is worse than no log, because it creates the feeling of control without any.

The part that reframed the job for me

In the PM literature this task is not called "track issues". It is called remove impediments — and the framing is deliberate. Tracking is bookkeeping. The job is clearing the path in front of your team.

That reads as soft-skills fluff until you notice it changes what you do on a Tuesday. Logging "waiting on legal review" is bookkeeping. Walking to legal, finding out the review is stuck on a question nobody asked them, and answering it — that is the job. The log exists to make sure you know which path to clear, not to be the work itself.

For anyone moving from senior dev toward lead or EM: this is a large part of what the role actually is, and it is nearly invisible from the IC seat. It looks like someone going to a lot of meetings. Sometimes it is. Sometimes it is the only reason your sprint finished.

If you want the longer version

I have been writing up the PMP exam content as practical lessons while studying it, with worked examples — the one on issue logs and removing impediments is here. It covers the risk→issue escalation path in more detail, and what the exam expects you to do when a blocker appears (short version: act to clear it, don't just log it).

Full disclosure: I build VanillaPM, an open project management tool, and the lessons are part of it. They are free and ungated — I wrote them to learn the material myself, and publishing them seemed better than letting the notes rot in a folder.

The one thing worth stealing from this post, if you take nothing else: separate the problems that are happening from the work you intend to do. They need different owners, different cadences, and different people reading them. One backlog cannot do both jobs, and the one it quietly stops doing is the one that sinks projects.

What is Playwright — and why it belongs in your Django toolkit

Ahsan Ahmad — Thu, 01 Oct 2026 09:13:59 +0000

Here's a scene every team knows. A change ships. The tests are green. The server returns 200. And then a customer emails a screenshot: the "Submit" button does nothing on their phone, and it's been broken for three days.

Nothing failed. The unit tests checked the functions. The API returned the right JSON. But no machine ever did the one thing that matters — open the page in a real browser and try to use it. That gap is exactly what Playwright fills, and it's the reason it's become the most useful tool in my Django kit that isn't Django itself.

This is the first of a four-part series. Today is the on-ramp: what Playwright is, why it matters, and the surprising range of things it can do — written so a developer gets the depth and the people who fund and lead the work get the point. (The next posts get hands-on: a full Django setup tutorial, then two real stories from building VanillaPM — automating a couple hundred product screenshots, and hunting a CSS bug that had no visible element.)

What Playwright actually is

Playwright is a tool that drives a real web browser the way a person would — it opens a page, clicks buttons, fills forms, waits for things to appear, and can then check what happened, take a screenshot, or measure the page. It's open source, made by Microsoft, and it speaks Python (and JavaScript, Java, and .NET).

The whole idea fits in one snippet:

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    page.goto("https://example.com")
    print(page.title())          # "Example Domain"
    page.screenshot(path="it-works.png")
    browser.close()

That's it. You just ran a real Chromium browser, loaded a page, read its title, and saved a picture of it — from Python, in ten lines. Everything else is variations on that theme.

Why it's necessary: the gap manual testing leaves

Most test suites are made of unit tests — they check a function returns the right value — and maybe API tests — they check an endpoint returns the right JSON. Those are essential and fast, and you should have hundreds of them. (VanillaPM has over two thousand.)

But none of them answer the question your users actually care about: can a human open this page and get their job done? Modern Django apps make that gap wider, not smaller — the moment you sprinkle in Alpine, HTMX, or any JavaScript, the server can return a perfect 200 while the rendered page is broken. Django's own test client doesn't run JavaScript; it never sees the bug.

The traditional patch is manual QA — a person clicks through the critical screens before each release. That works right up until it doesn't:

It's slow and repetitive — the same clicks, every release, forever.
It's inconsistent — humans get bored, skip steps, and test different things each time.
It doesn't scale — ten features become a hundred, and no one can re-click everything.

Playwright turns that click-through into code that runs in seconds, the same way, every single time — in your CI pipeline, before anything reaches a user.

💼 For the people who sign off on the work

(A lane for business and policy leaders — skip ahead if you're here for the code.)

Strip away the tooling and the pitch is simple: software that isn't tested by machines is tested by your customers. Automated browser testing moves the moment you discover a broken screen from "a user reported it" to "the pipeline caught it before it shipped."

Why that matters where it counts:

The cost of a bug grows the later you find it. Caught in CI, a broken checkout flow costs a developer a few minutes. Caught in production, it costs support tickets, an emergency release, and — the expensive one — trust. Automated checks shift that cost left, to its cheapest point.
It lets a small team move fast without breaking what already works. This is the real unlock. One developer built VanillaPM — a fifty-module platform — and ships changes confidently because 2,225 automated checks run on every change and scream if anything regresses. That's not heroics; it's leverage. Automation is how few people safely maintain a lot of software.
It turns "done" into something you can verify. For anyone commissioning software — including public-sector and regulated buyers — "the critical user journeys are covered by automated browser tests" is a concrete, auditable acceptance criterion. It's a line you can put in a contract and a vendor can prove, instead of taking "it works" on faith.

The one-line version for a board slide: automated testing is insurance against your own releases — a one-time build that pays out on every change, forever.

What it can do (the part that surprises people)

"Playwright is for testing" is true but undersells it badly. Because it can drive a real browser and read anything on the page, the same tool covers a remarkable spread of jobs:

End-to-end tests — the headline use. Prove a real journey works, start to finish:

def test_user_can_log_in(page):
    page.goto("http://localhost:8000/login/")
    page.fill("#email", "demo@example.com")
    page.fill("#password", "secret")
    page.click("button[type=submit]")
    assert page.get_by_role("heading", name="Dashboard").is_visible()

Screenshots, on demand — point it at any screen and capture a pixel-perfect image. Great for docs, marketing, and visual-regression checks:

page.screenshot(path="dashboard.png", full_page=True)

PDF generation — render any page straight to a PDF (headless Chromium):

page.pdf(path="report.pdf", format="A4")

Scraping & data extraction — read content from pages that only exist after JavaScript runs, which plain requests + BeautifulSoup can't reach:

titles = page.locator("h2.product-title").all_text_contents()

Cross-browser, from one script — the same code runs on Chromium, Firefox, and WebKit (Safari's engine), so you catch the "works in Chrome, broken in Safari" class of bug:

for engine in [p.chromium, p.firefox, p.webkit]:
    browser = engine.launch()
    # ... run the same checks ...

Mobile emulation — load any page as a specific device, with the right viewport and touch behaviour:

iphone = p.devices["iPhone 13"]
context = browser.new_context(**iphone)

Debugging — and this is the sleeper. Because you can run arbitrary JavaScript in the page and read the result, Playwright becomes a measuring instrument:

overflow = page.evaluate(
    "() => document.documentElement.scrollWidth - document.documentElement.clientWidth"
)

That one line is how I pinned down a mobile layout bug that no human eye could isolate — the page scrolled sideways but nothing on screen looked wrong. (That's the war story in Part 4 of this series.)

In VanillaPM, Playwright does three of these jobs in production-adjacent anger: it runs the end-to-end smoke tests, it captures a couple hundred product screenshots for the investor deck and docs on command, and it's my go-to debugging probe. One tool, three very different jobs.

Why Django especially

Two reasons Playwright and Django are a natural pair:

The JavaScript gap is real in Django apps. Django's test client is excellent and fast — but it's HTML-only. The moment your templates lean on Alpine or HTMX for interactivity, you need something that executes that JavaScript to know the page actually works. Playwright is that something.
Django hands you a server to test against. StaticLiveServerTestCase spins up a real, running instance of your app inside the test — the perfect target for Playwright to drive. The two slot together with almost no glue. (That's the whole of Part 2.)

🧭 For engineering leaders

(A lane for the people deciding whether to adopt this.)

A few framing calls worth making deliberately:

It's the thin top of the testing pyramid, not a replacement for it. End-to-end tests are powerful but slow and comparatively expensive to maintain. Keep the base of the pyramid wide (fast unit tests), and use Playwright for a small, high-value set of critical journeys — login, checkout, the one flow that must never break. Teams that try to test everything through the browser end up with a slow, flaky suite they learn to ignore.
Budget honestly for flakiness. Browser tests fail for boring reasons — a selector moves, a timing assumption breaks. (I recently spent an afternoon on a test that failed only on CI because of filesystem ordering — the flaky-test tax is real.) Playwright's auto-waiting removes most of it, but plan for some maintenance rather than pretending it's free.
The build-vs-buy math is friendly. It's open source with no per-seat licensing, and one tool covers three browser engines, mobile emulation, a recorder that writes tests for you (playwright codegen), and a trace viewer that replays a failed run step by step. The adoption cost is genuinely low — which matters for a small team or a tight budget.
The ROI is bigger than "tests." The same capability de-risks refactors (change internals confidently behind a safety net), gates your CI, and doubles as automation infrastructure — screenshots, PDFs, uptime checks. You buy one skill and get several capabilities.

The honest caveats

This crowd rewards honesty, so: Playwright is not a silver bullet. End-to-end tests are slower than unit tests, they can be flaky if you lean on brittle selectors, and they need upkeep as the UI changes. The discipline is to use them surgically — for the handful of journeys that genuinely matter — and let fast unit tests do the heavy lifting underneath. Reach for the browser when, and only when, the thing you need to verify only exists in the browser.

What's next

That's the why. The rest of this series gets concrete:

Part 2 — the tutorial: setting up Playwright with Django properly, start to finish (the StaticLiveServerTestCase pattern, logging in once, selectors that don't rot, CI).
Part 3 — automation: how I automated a couple hundred product screenshots with one script.
Part 4 — debugging: finding a CSS bug that had no visible element.

If you've been meaning to close the gap between "the tests pass" and "the page actually works," this is the tool that does it.

I write this series while building VanillaPM — a free, full-lifecycle project-management platform — in the open. Follow along for more build-in-public engineering.

Grounded AI: making an LLM draft a project charter from real data — without hallucinating

Ahsan Ahmad — Fri, 18 Sep 2026 05:47:06 +0000

"Add AI" is the easiest line item on any 2026 roadmap and the easiest way to ship something worse than nothing. Wire an LLM to a "Generate charter" button, feed it the project name, and it will happily produce a beautifully-worded project charter full of objectives, success criteria and stakeholders that do not exist. In a governed project-management tool, a confident invention is worse than a blank field — someone might believe it.

I wanted the generate button anyway, because there's a real version of it. Here's how I built a charter generator that drafts genuinely useful prose from the user's actual data, and refuses to make things up — in Django, bring-your-own-key, no framework magic.

Two things this is not

Not autopopulate. I already had a deterministic autopopulate: copy the sponsor from the project record, the dates from the schedule, and so on. That's great for fields, but a charter is mostly prose — a scope statement, an objectives section, a rationale — synthesised from the pre-project inputs (the business case, the benefits plan, the agreements). You can't str() your way to a scope statement. Autopopulate structurally can't do it.

Not a free-form LLM. The other extreme — "here's the project name, write me a charter" — is exactly the hallucination machine. The model has no idea what your business case says, so it invents a plausible one.

The useful thing lives in between: grounded synthesis. Read the real input documents, and ask the model to compose — using only what's actually there.

Step 1: ground in the real inputs, not the model's imagination

The whole trick is that the model's only source of truth is text you supply from the user's own documents — never its training data.

In VanillaPM every document type declares its input documents (its ITTO prerequisites — the things that must exist before it). A charter's inputs are the business case, the benefits management plan, the agreements. So "grounding" is concrete: go read those documents.

DOC_CHAR_CAP     = 8_000    # per input document
TOTAL_CONTEXT_CAP = 40_000  # the whole grounding context

def input_documents(project, doc_type):
    """(type, title, text) for each declared prerequisite that exists and has
    readable text — each capped so one long doc can't dominate the context."""
    out = []
    for prereq in prerequisite_types(project, doc_type):   # from the dependency graph
        doc = latest_of_type(project, prereq)
        text = document_text(doc)          # walk the stored rich-text → plain text
        if text:
            out.append((prereq, doc.title, text[:DOC_CHAR_CAP]))
    return out

Two boring-but-important details:

Cap per document and in total. One 200-page attachment shouldn't crowd out the other inputs (or blow your context window / bill). A per-doc cap plus a total cap keeps the grounding balanced and bounded.
Ground in authored text, not the whole DB. document_text() walks the document's stored rich-text tree and pulls the prose the human actually wrote — not a JSON dump of every model.

The grounding context is then just: the deterministic structured facts (reused from autopopulate) + these input-document excerpts, under a big honest header.

Step 2: the system prompt does the anti-hallucination work

This is the part people skip. The model will fabricate unless you make refusing the easier path. Three rules, and the second one is the whole ballgame:

SYSTEM_PROMPT = (
    "You draft sections of a PMBOK-aligned project document.\n"
    "1. Ground every section ONLY in the provided project data and input "
    "   documents below. They are your only source of truth.\n"
    "2. If the data a section needs is missing, write ONE short professional "
    "   sentence stating what input is still needed — do NOT fabricate.\n"
    "3. Return JSON only: "
    '{"sections":[{"key":"<section_key>","body":"<prose>"}]}. '
    "Use only the section keys given. No markdown headings, no preamble."
)

Rule 2 is the difference between a demo and a tool. Giving the model an acceptable way to say "I don't have this" — a short "needs input: the benefits plan doesn't state a target ROI" placeholder — means it takes that exit instead of inventing a number. You're not just asking it not to hallucinate; you're handing it a better move than hallucinating.

The user turn wires the sections to draft onto the grounding context:

USER_PROMPT = (
    "Draft these sections of the project's {doc_label}. Use each key exactly:\n\n"
    "{targets}\n\n"
    "=== PROJECT DATA AND INPUT DOCUMENTS (your only source of truth) ===\n"
    "{context}"
)

Structured JSON out, fixed keys in. The model returns {"sections":[{"key", "body"}]} and may only use keys I gave it. That does two jobs: parsing is trivial and deterministic, and the model can't wander off and invent a "Section 12: Executive Bonus Plan." It fills the blanks I asked for, or it says it can't.

Step 3: only touch the blanks, never the real data

A charter is a mix of authored prose sections and live-data sections (a stakeholder table, a risk snapshot) that are generated from real records. The AI must never touch the latter — those aren't opinions to draft, they're facts to render.

def target_sections(content_json, overwrite=False):
    for node in content_json.get("content", []):
        if section_has_datablock(node):        # a live register/table snapshot
            continue                           # generated from real data — hands off
        if section_has_text(node) and not overwrite:
            continue                           # non-destructive: only fill empty sections
        yield node["attrs"]["key"], node["attrs"]["title"]

So the fill is non-destructive (it never overwrites what a human wrote unless they ask) and it skips live-data sections entirely. The model works on empty prose sections and nothing else. Bonus: because the section keys/titles come from the document itself, the exact same code drafts a communications plan or a risk-management plan — it generalised for free.

And the output lands in draft, for a human to review and approve. The AI proposes; the PM decides. It's never a fact until a person signs off.

Step 4: bring-your-own-key, and fail safe

No forced AI markup, and no crash when AI isn't configured. The path resolves BYOK-first:

def resolve_ai_path(user, org):
    if byok_available(user, org):                     # user's own key
        return "byok", user_key(user), MODEL_BYOK     #   → free through us
    if managed_available(user, org):                  # metered credits
        return "managed", server_key(), MODEL_MANAGED
    return None, None, None                           # feature cleanly disabled

And the SDK import is guarded — a server without the anthropic package (or a user without a key) degrades to a disabled button, never an exception:

try:
    import anthropic
    _AVAILABLE = True
except ImportError:
    anthropic, _AVAILABLE = None, False

Nothing in the module holds a key; the caller passes the user's decrypted key in per request. (Load tests swap in an offline stub so they never hit the real API — cost and rate limits stay off the test path.)

What grounding buys you — and what it doesn't

Grounding isn't a hallucination cure; it's a hallucination budget. What it reliably buys:

The model composes from your business case, so the objectives are your objectives.
Missing inputs surface as honest "needs input" notes — which doubles as a checklist of what to go write.
Structured, key-scoped output means no invented sections and trivial parsing.
Non-destructive, draft-only, human-approved: the AI can't silently rewrite a governed document.

What it doesn't do: it won't fix a vague business case (garbage in, grounded-garbage out), and a determined model can still mis-synthesise. So it's a draft generator with a human gate, not an autopilot — which is exactly what a governed document deserves.

The pattern generalises well beyond charters: read the real inputs, cap and label them as the only source of truth, give the model an honest "I don't know," constrain the output shape, and never let it touch data it should only render. That's most of the distance between "we added AI" and AI you can actually put near real work.

I'm building a free, full-lifecycle PM platform in the open — this generator ships in it (BYOK). If the build-in-public engineering is your thing, the rest of the series is here.

Keeping Alpine.js + Django templates sane in a large app

Ahsan Ahmad — Mon, 07 Sep 2026 10:33:22 +0000

I built a big app the "boring" way: server-rendered Django templates + Alpine.js for interactivity, no SPA. ~50 Django apps, a lot of screens, one developer. Alpine is the perfect amount of JavaScript for this — until the app gets large and you start hitting its sharp edges.

Here are the patterns that kept it maintainable, and the gotchas that cost me real hours. All of it is stuff I wish someone had told me at line 1.

The mental model: islands, not an app

The trap with Alpine in a big project is treating it like a mini-SPA — global stores everywhere, components reaching into each other. Don't. Treat each interactive region as an island: a self-contained Alpine component hydrating one chunk of server-rendered HTML. The server owns the data and the page; Alpine owns this widget's behaviour.

Two rules fall out of that, and they're the difference between "fine at 10 screens" and "fine at 200."

Rule 1: register components — stop writing logic inline

Inline x-data="{ ... }" is lovely for a toggle. For anything real, it's a liability — and it has a nasty failure mode.

Put a literal double-quote inside an inline expression and you silently close the HTML attribute early:

<!-- ❌ Alpine sees x-data="{ label: "  — the rest becomes broken markup -->
<div x-data="{ label: "Save", open: false }">

The component doesn't throw. It just… doesn't initialize, and depending on where the parser gives up, your expression can dump into the page as visible text. Worse, it often renders fine in your quick manual check but breaks somewhere else — and it's invisible to a lot of smoke tests because it's an HTML-parse issue, not a JS error.

The fix isn't "remember to use single quotes." It's: anything beyond a line or two becomes a registered component.

// static/js/components.js
document.addEventListener('alpine:init', () => {
  Alpine.data('projectBoard', () => ({
    open: false,
    label: 'Save',           // real quotes, real editor, real linting
    toggle() { this.open = !this.open },
  }))
})

<div x-data="projectBoard"> … </div>

Now the logic lives in a .js file your editor and linter understand, the template stays declarative, and the quoting footgun is gone.

Rule 2: never put a "rich" JS instance on reactive state

This one cost me the most time, so I'll be specific. Alpine makes your state reactive by wrapping it in a deep Proxy (via @vue/reactivity). That's great for plain data. It's poison for objects that do their own identity bookkeeping internally — a TipTap/ProseMirror editor, a map instance, a <canvas> controller, a WebSocket.

// ❌ ProseMirror starts throwing "Applying a mismatched transaction"
Alpine.data('editor', () => ({
  editor: null,
  init() { this.editor = new Editor({ element: this.$refs.box }) }, // now a Proxy
}))

The editor stores references to its own nodes/state and compares them by identity. Once Alpine has proxied it, this.editor is not the object the editor thinks it is, and its internal === checks fail in baffling ways.

The fix: keep non-plain instances off reactive state entirely. A closure is cleanest:

// ✅ the editor lives in closure scope — never proxied
Alpine.data('editor', () => {
  let editor
  return {
    init()    { editor = new Editor({ element: this.$refs.box }) },
    bold()    { editor.chain().focus().toggleBold().run() },
    destroy() { editor?.destroy() },
  }
})

If it must live on this, mark it so the reactivity engine skips it (obj.__v_skip = true before assigning, i.e. markRaw). But closure scope is simpler and I reach for it every time. Rule of thumb: only plain, serializable data goes on x-data.

Rule 3: `x-data` initializers snapshot — use `init`/`x-effect` for async

x-data runs once, eagerly, and takes whatever the expression evaluates to right then.

<!-- ❌ `stats` is the Promise fetchStats() returned, not the resolved data -->
<div x-data="{ stats: fetchStats() }">

You'll see [object Promise] or stale/empty state and chase it for an hour. Load then assign:

<div x-data="{ stats: null, async init() { this.stats = await fetchStats() } }">
  <template x-if="stats">…</template>
</div>

Same shape bit me with theme switching: reading a value once at init captures it forever. If something needs to react to a change (a store value, a media query, a fetched result), it belongs in x-effect or an explicit assignment — not in the initializer expression.

Rule 4: pass server data as data, not string interpolation

The tempting thing is to jam Django context straight into an Alpine expression: x-data="{ items: {{ items }} }". It works until a value contains a quote or a newline, and then you're back in Rule 1's parser hell. Use Django's json_script:

{{ items|json_script:"board-data" }}

<div x-data="{ items: JSON.parse(document.getElementById('board-data').textContent) }">

Server renders JSON safely into a <script type="application/json">; Alpine reads it. Clean separation: Django owns the data, the template just carries it, Alpine consumes it.

The small Django-template traps

Two that bit me more than once:

{# … #} is single-line only. A comment that wraps across lines renders as literal visible text — and if it's sitting next to an Alpine attribute, chaos. Use {% comment %} … {% endcomment %} for anything multi-line.
Shared islands, single-sourced. The nav bar, the sidebar, the top bar — build each as one island partial you include everywhere, not a per-page fork. The day I stopped copy-pasting the nav component was the day the footer stopped mysteriously drifting between pages.

What "sane" ended up meaning

Nothing exotic — just discipline:

Islands, not a SPA. Server owns data + page; Alpine owns a widget.
Register non-trivial components in a JS file; inline only for toggles.
Plain data only on x-data — rich instances live in closures.
Async loads via init/x-effect, never the initializer expression.
Server → client via json_script, never string interpolation.
A browser smoke run as a release gate, because the worst Alpine bugs are HTML-parse issues that pass unit tests.

Alpine scaled to a genuinely large app for me — but only once I stopped treating it like React-lite and started treating it like sprinkles on server-rendered HTML.

I write these while building a free, full-lifecycle PM platform in the open — if the build-in-public stuff is your thing, the rest of the series is here.

Why I made my project-management SaaS 100% free (and how I plan to survive)

Ahsan Ahmad — Wed, 02 Sep 2026 06:04:34 +0000

In my last post, I wrote up what it cost to build VanillaPM — a full PMBOK project-management platform — solo in three months. The reaction was kind. But almost every reply circled the same question:

"It's genuinely free? How are you going to survive?"

Fair question. Here's the honest answer — including the part where I admit I don't have it all figured out.

First, what "free" actually means here

Not a free trial. Not free-for-3-users-then-a-wall. The entire core is free — the full PMBOK 8th-edition lifecycle, charter to closeout, WBS, Gantt, Earned Value, risk registers, a knowledge base, sprints. No seat limits. No paywall on the thing itself. New accounts even open a fully-built sample project so you can use everything on real data before you create anything.

I did that on purpose, and it wasn't a growth hack.

Why free — the real reason

The tools that genuinely teach you project management are locked behind enterprise pricing. The ones you can actually afford don't teach you anything — they're glorified to-do lists. So the people who most need to learn how to run a project — a student, a freelancer, a first-time founder, a small NGO running on grants — are the exact people priced out of the tools that would teach them.

I wanted to close that gap. Free removes the friction for precisely the people who need it most. That's the whole point, and a paywall on the core would defeat it.

The bigger bet

Here's the part that reframes the "how will you survive" question: VanillaPM isn't "a free PM tool." It's the first module of a teaching business suite.

Project management is the front door because it's where most people first hit the wall. But finance, HR, payroll and org design are already being built on the same spine — the idea being that a small org could eventually run its whole operation, and learn how to, in one place. Free PM is distribution and trust. The moat is the teaching and the breadth that follows.

So… how do I plan to survive?

Honestly? I have directions, not a locked plan — and I'd rather tell you that than pretend I have a tidy spreadsheet.

What I'm considering (none decided):

Managed AI, not manual AI. Bring-your-own-key AI is free. But hosting the AI — no key, no setup, it just works — is a real cost I could reasonably charge for. Convenience, not capability.
Depth for organisations. The ERM finance-to-payroll suite, org-scoped access control at scale, multi-entity separation — the stuff a company needs, not a student. That's where willingness-to-pay actually lives.
Hosted / support / SLA tiers for teams who want someone on the hook.
The teaching layer — deeper courses, certifications-prep, guided tracks.

What I will never do:

Paywall the core PM lifecycle. It stays free.
Seat-limit the free tier into uselessness.
Sell your data. Ever.

The principle I keep coming back to: money should come from depth and convenience, not from holding your project hostage. The free core is a promise, not a funnel with a trapdoor.

The honest risk

This might not work. "Free core, charge for depth" is a real model (it's how a lot of good software gets distributed), but plenty of founders have gone broke being generous. I know that.

I'm building in public partly because I don't have it fully solved — the feedback is the point. Free-first is a deliberate bet: distribution and trust now, revenue later, from the people and orgs who get enough value that paying feels obvious rather than extracted.

Ask me again in a year and I'll show you the numbers — the good and the bad. I've been sharing the flops too (my first ad: $3, some clicks, zero signups), and I'm not going to stop.

Your turn

If you've built or used a free-core product: how would you monetise this without betraying the "free" promise? Genuinely asking — the comments on posts like this have already changed my thinking more than any strategy deck.

And if you just want to poke at a free, full-lifecycle PM platform (no signup wall — there's a sample project waiting): it's at vanillapm.com.

I built a full PMBOK project-management platform solo in 3 months — here's what it cost

Ahsan Ahmad — Tue, 01 Sep 2026 06:40:59 +0000

Three months ago, VanillaPM was an empty Django project. Today it runs the entire PMBOK 8th-edition project lifecycle — Initiating through Closing — with a work breakdown structure, critical-path scheduling, Earned Value, risk and assumption registers, a governed knowledge base, sprints, an ERM finance-to-payroll suite, and a bring-your-own-key AI assistant. It's live, it has over 2,000 automated tests, and it's completely free.

I'm a developer of ~13 years who spent the last few leading delivery, and I wanted to genuinely learn formal project management — not from slides, but by building the tool I wished existed. This is the honest breakdown: what it cost in money, where the real leverage came from, and a few lessons that surprised me.

What it actually cost

Item	Cost
VPS — 12 months, prepaid	$203.88
Business email — 48 months	$228.96
AI credits (the build phase)	$150.00
One-time, to a shipped 1.0	$582.84
Recurring during the build	~$46 / month

Total to a shipped, tested, deployed 1.0: under $700. No team, no seed round, no office — a $17/month VPS, a mailbox, and some AI credits.

The line item that matters most is the smallest: that $150 of AI credits is the one that changed what "solo" even means.

The real lever: AI as a force multiplier, not an autocomplete

The interesting part isn't that AI wrote code. It's that it let one person hold the whole system in their head at team throughput. Scaffolding a new Django app, writing the tests alongside the feature, doing the third tedious refactor of the day, rubber-ducking an architecture decision, and — genuinely — teaching me the PMBOK concepts while I built the features that implement them.

It is not magic, and it doesn't replace judgment. You still architect. You still decide. You still verify everything, because the model is confidently wrong often enough that trusting it blindly would sink you. But the throughput multiplier is real, and the shape of "what a solo developer can ship" has changed.

Some concrete numbers from the three months:

58 Django apps
~84,000 lines of Python (excluding migrations)
320 migrations of schema evolution
2,000+ tests, behind a CI gate that blocks any merge on a failing test or a coverage drop

Every task got its own branch, ran tests + lint + a makemigrations --check on every change, and merged with --no-ff. That discipline is the thing AI didn't replace — it amplified it.

Four lessons that surprised me

1. Tests are what make solo + AI safe. Those 2,000 tests aren't a vanity metric — they're the safety net that lets you refactor fearlessly and trust an AI-assisted change you didn't hand-write line by line. Without them, the speed becomes a liability. With them, it compounds.

2. Building the PM tool taught me PM better than any course. I ran the build of VanillaPM as a VanillaPM project — a real charter, a WBS, sprints, formal change control on my own scope. Dogfooding turned abstract PMBOK concepts into muscle memory.

3. The boring infrastructure decisions compound. Postgres end-to-end, object storage for files, a fail-closed search-indexing gate, automated backups, a health-checked deploy. None of it is exciting. All of it is why the thing stays up.

4. Scope is the enemy, and formal change control on your own project keeps you honest. The number of "small" features I talked myself out of via my own change process is the reason 1.0 shipped at all.

Why it's free

The tools that actually teach you project management are locked behind enterprise pricing; the ones you can afford don't teach you anything. I wanted to close that gap — a place where a student, a freelancer, or a small NGO can run a real project (and learn how) without a paywall. New accounts even drop straight into a fully-built sample project — a 220-room hotel build with a real WBS, schedule, budget and risk register — so you can explore everything on real data before creating anything of your own.

There's also a free Learn PMP course and an ITTO memory game for exam prep, in seven languages.

If you want to look

It's at vanillapm.com — free, no trial, no seat limits. I'm building the rest in public and I'll keep sharing the numbers, including the unflattering ones (my first paid ad: $3, a handful of clicks, zero signups — but that's another post).

If you're a developer curious about the solo-plus-AI workflow, or a PM tired of enterprise pricing, I'd genuinely love your feedback in the comments. What would you have built differently?