DEV Community: Balaji K

Scaling Playwright E2E Tests with a Role-Aware Mockserver

Balaji K — Wed, 03 Jun 2026 17:17:21 +0000

A real working implementation with admin, viewer, and VIP UI flows
What We Are Building
Role Behavior in the UI
Mockserver: Auth-Style Backend Stub
Playwright Adds Role Headers to Mockserver Requests
Mockserver Signs Roles Into the ID Token
The App Uses the Token to Load Role-Specific Workspace Data
The Protected Workspace Endpoint Verifies the Token
Feature Flags Use the Same Header Pattern
Backend Error Scenarios Are Also Header-Driven
Playwright Projects Run the Role Matrix
The Role UI Test
Positive and Negative Role Checks
Multiple Roles Are Supported
Running the Project
Why This Scales
Lessons Learned
Conclusion
Credits

A real working implementation with admin, viewer, and VIP UI flows:

End-to-end tests usually start with a simple flow: open the app, log in, perform an action, assert the result.

That works until the application starts behaving differently based on the logged-in user's role.
For example:

An admin can manage users, review audit logs, and perform security overrides.
A viewer can search profiles and view reports, but cannot mutate anything.
A vip support agent can access priority handling tools and concierge notes.

If those scenarios depend on real identity providers, real test users, seeded permissions, and live backend state, the suite becomes slow and fragile. The tests are no longer only testing the UI. They are also depending on auth availability, user setup, backend data, and environment stability.

In a scalable automation project, the answer is not to push every scenario into full E2E. The better approach is to decide which layer should own which type of confidence.

For role-based testing, I usually think about the strategy like this:

That separation is important. The mocked E2E layer gives fast and deterministic coverage for role behavior. Integration and smoke tests prove that the real environment still connects correctly. They should complement each other instead of competing to test everything at the most expensive layer.

The architecture below focuses on the mocked Playwright E2E layer. The goal is to make role-based UI scenarios fast, repeatable, and explicit, while still leaving space for integration and smoke tests elsewhere in the delivery pipeline.

There is also an important evolution here.
In the initial version of the framework, Playwright route interception was used against real integration tests. The tests still navigated through the real application environment, but intercepted selected network calls and modified requests or responses to force edge cases.

That approach is useful when starting out, especially for one-off scenarios. But as the role matrix grows, it can become flaky in CI/CD because the test is still coupled to real auth, real backend availability, seeded users, changing data, and environment timing.
The more scalable version moves that responsibility into a mockserver.

So in the final mockserver setup, Playwright still uses page.route(), but only to continue requests to the local mockserver with test headers. It does not directly fulfill the production-like API response. The mockserver owns the actual auth token, config, workspace, role, feature flag, and error responses.

I also keep one comparison test in the sample project for the earlier style:

playwright/tests/legacy-network-interception.spec.ts

That test directly fulfills the UI config, token, and workspace API calls from Playwright. It is useful for explaining the migration path, but it is not the preferred scalable pattern for the role matrix.

The implementation below solves that by using:

a local application,
a Koa-based backend mockserver,
a mocked auth/token flow,
signed JWT id_token roles,
Playwright route continuation to add test headers,
and role-specific UI assertions.

This is not just a concept. The project runs locally and the Playwright suite verifies admin, viewer, and vip roles with different UI functionality.

The complete working example is available here:
https://github.com/balajiregt/plawright-role-aware-mockserver

Local Demo vs Real Stubbed Functional Environment

The GitHub project uses a local mockserver so the full idea can be cloned, run, and understood without any company infrastructure.

In a real project, this pattern usually lives in a dedicated stubbed functional environment. That environment is deployed and maintained like any other test environment, often with solution/platform/SRE involvement. The frontend points to a controlled BFF or mockserver layer, and the mockserver serves deterministic stubbed responses instead of depending on live downstream systems.
The important difference is this:

That deployed stubbed functional environment is what makes the approach practical at scale. The local repo is a simplified, public version of the same testing idea.

What We Are Building

The project has three parts:

real-role-auth-mockserver-project/
├── app/
│   ├── server.mjs
│   └── public/
│       ├── index.html
│       ├── app.js
│       └── styles.css
│
├── mockserver/
│   └── src/
│       ├── mock-server.js
│       └── backend/
│           ├── index.js
│           ├── utils.js
│           └── endpoints/
│               ├── auth/
│               │   ├── token.js
│               │   ├── jwks.js
│               │   ├── authorize.js
│               │   └── well-known.js
│               └── v1/
│                   ├── ui-config.js
│                   └── workspace.js
│
└── playwright/
    ├── playwright.config.ts
    ├── helpers/
    │   └── api-mock.ts
    ├── pages/
    │   ├── operations-console.page.ts
    │   └── operations-console.assertions.ts
    └── tests/
        ├── role-ui.spec.ts
        ├── feature-flags.spec.ts
        └── legacy-network-interception.spec.ts

The local app does not hardcode the role. It calls the mockserver just like a real frontend would:

Load UI config from /bff/v1/ui-config.
Request a token from /bff/auth/token.
Decode the returned id_token.
Send that token to /bff/v1/workspace.
Render role-specific actions from the protected workspace response.

Playwright changes the role by continuing the token request with an agent-roles header.

The mockserver then owns the behavior: it reads that header, signs those roles into the id_token, and returns the role-aware workspace response.

That is the key boundary.

Role Behavior in the UI

The app has three roles, each with unique UI functionality.

| Role   | Workspace                  | Visible actions |
| :---   | :--------                  | :-------------- |
| admin  | Admin Operations Workspace | User Admin Console, Security  Override, Audit Log |
| viewer | Read-Only Viewer Workspace | Profile Search, Read-Only Dashboard, View Reports |
| vip    | VIP Support Workspace      | VIP Support Desk, Priority Override, Concierge Notes |

Manual browser usage defaults to viewer, because no Playwright test is injecting roles.

Playwright drives the full role matrix.

Mockserver: Auth-Style Backend Stub

The mockserver is a Koa app.

import Koa from 'koa';
import Router from '@koa/router';
import mount from 'koa-mount';
import cors from '@koa/cors';
import bodyParser from '@koa/bodyparser';
import { generateKeyPairSync } from 'node:crypto';
import bffRoutes from './backend/index.js';

export const { privateKey, publicKey } = generateKeyPairSync('rsa', {
  modulusLength: 2048,
});

export const issuerUri = 'http://127.0.0.1:3333/bff/auth';

const app = new Koa();
const router = new Router();

app.use(cors({
  origin: 'http://127.0.0.1:5173',
  credentials: true,
  allowHeaders: [
    'content-type',
    'authorization',
    'agent-roles',
    'override-feature-flags',
    'downstream-error',
  ],
}));

app.use(bodyParser());

router.get('/', (ctx) => {
  ctx.body = 'BFF mock server';
});

app.use(router.routes()).use(router.allowedMethods());
app.use(mount('/bff', bffRoutes()));

The backend router exposes auth, config, and workspace endpoints.

router.get(/^\/auth\/authorize/, authorize);
router.post(/^\/auth\/token/, token);
router.get('/auth/jwks', jwks);
router.get(/^\/auth\/(.*)v2.0\/\.well-known\/openid-configuration$/, wellKnown);

router.get('/v1/ui-config', uiConfig);
router.get('/v1/workspace', workspace);

This gives the local app a realistic backend shape:

token endpoint,
JWKS endpoint,
well-known configuration endpoint,
UI config endpoint,
protected workspace endpoint.

Playwright Adds Role Headers to Mockserver Requests

The role helper is deliberately small. It continues the token request and adds the role header that only the mockserver understands.

import { Page } from '@playwright/test';

export type AgentRole = 'admin' | 'viewer' | 'vip';

export async function mockAgentRoles(page: Page, roles: AgentRole[]) {
  await page.route('**/auth/token**', async (route, request) => {
    await route.continue({
      headers: {
        ...request.headers(),
        'agent-roles': roles.join(','),
      },
    });
  });
}

This mirrors the stabilized pattern used in the real framework: the test does not directly modify the DOM, local storage, frontend state, or fulfill production-like integration responses. It only adds test metadata to requests that are already going to the local mockserver.

A test can say:

Mockserver Signs Roles Into the ID Token

The token endpoint reads the agent-roles header.

const roles = parseCsvHeader(ctx.get('agent-roles'));
const normalizedRoles = roles.length ? roles : ['viewer'];

Then it places those roles into the ID token payload.

const idTokenPayload = {
  sub: 'local-demo-user',
  aud: 'identity-manager-frontend',
  iss: issuerUri,
  name: 'Role Demo User',
  preferred_username: 'role.demo@example.test',
  iat: now,
  exp: now + 3600,
  roles: normalizedRoles,
};

Finally, it signs the token using the mockserver’s private key.

ctx.body = {
  token_type: 'Bearer',
  expires_in: 3600,
  access_token: jwt.sign(accessTokenPayload, privateKey, signOptions),
  refresh_token: ctx.request.body?.refresh_token || 'local-refresh-token',
  id_token: jwt.sign(idTokenPayload, privateKey, signOptions),
};

This is what makes the demo realistic. The frontend is not receiving a fake role variable from Playwright. It is receiving a signed token from the mockserver.

The App Uses the Token to Load Role-Specific Workspace Data

The frontend calls /auth/token, decodes the returned id_token, then calls the protected workspace endpoint with that token.

const tokenResponse = await getJson('/auth/token?client-request-id=role-demo', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    scope: 'openid profile',
    refresh_token: 'local-demo-refresh-token',
  }),
});

const tokenPayload = decodeJwtPayload(tokenResponse.id_token);

const workspace = await getJson('/v1/workspace', {
  headers: {
    authorization: `Bearer ${tokenResponse.id_token}`,
  },
});

The app renders what the workspace endpoint returns.

elements.roleList.textContent = roles.join(', ');
elements.workspaceTitle.textContent = workspace.title;
elements.workspaceSummary.textContent = workspace.summary;
elements.actionCount.textContent = `${workspace.actions.length} actions`;

Each action becomes a real UI card.

for (const action of workspace.actions) {
  const card = document.createElement('article');
  card.dataset.testid = `action-${action.id}`;
  card.innerHTML = `
    <span>${action.category}</span>
    <h3>${action.label}</h3>
    <p>${action.description}</p>
  `;
  elements.actionGrid.append(card);
}

So the UI is genuinely different for admin, viewer, and vip.

The Protected Workspace Endpoint Verifies the Token

The workspace endpoint does not blindly trust a role header. It reads and verifies the bearer token

const token = tokenFromAuthHeader(ctx);

if (!token) {
  ctx.status = 401;
  ctx.body = { message: 'Missing bearer token' };
  return;
}

Then it verifies the JWT using the public key.

const payload = jwt.verify(token, publicKey, {
  algorithms: ['RS256'],
  audience: 'identity-manager-frontend',
});

The endpoint selects the primary role and returns the matching workspace.

const roles = Array.isArray(payload.roles) ? payload.roles : ['viewer'];
const primaryRole = selectedPrimaryRole(roles);

ctx.body = {
  primaryRole,
  roles,
  ...actionCatalog[primaryRole],
};

The role precedence is explicit:

export function selectedPrimaryRole(roles) {
  if (roles.includes('admin')) return 'admin';
  if (roles.includes('vip')) return 'vip';
  return 'viewer';
}

This also supports multiple-role users.

Feature Flags Use the Same Header Pattern

Roles are not the only thing that changes UI behavior. Feature flags can be controlled through the same mockserver header pattern.

export async function setFeatureFlags(
  page: Page,
  featureFlagSetup: FeatureFlagSetup,
) {
  await page.route('**/v1/ui-config**', async (route, request) => {
    await route.continue({
      headers: {
        ...request.headers(),
        'override-feature-flags': JSON.stringify(featureFlagSetup),
      },
    });
  });
}

The mockserver returns either default flags or the override.

const overrideFeatureFlags = ctx.get('override-feature-flags');

ctx.body = {
  azure: {
    issuerUri: 'http://127.0.0.1:3333/bff/auth',
    clientId: 'local-demo-client',
    apiScopes: ['openid', 'profile'],
  },
  featureFlags: overrideFeatureFlags
    ? JSON.parse(overrideFeatureFlags).featureFlags
    : defaultFeatureFlags,
};

This makes feature-gated UI easy to test without changing application code.

Backend Error Scenarios Are Also Header-Driven

The same pattern can force downstream failures.

export async function mockDownstreamServerError(page: Page) {
  await page.route('**/bff/v1/workspace**', async (route, request) => {
    await route.continue({
      headers: {
        ...request.headers(),
        'downstream-error': 'true',
      },
    });
  });
}

The mockserver turns that into a deterministic backend failure.

const downstreamError = ctx.get('downstream-error') === 'true';

if (downstreamError) {
  ctx.status = 503;
  ctx.body = {
    message: 'Mocked downstream workspace service failure',
  };
  return;
}

This is useful for error handling tests that are painful to reproduce against live systems.

Playwright Projects Run the Role Matrix

The Playwright config defines three projects.

projects: [
  {
    name: 'admin',
    use: { ...devices['Desktop Chrome'] },
    metadata: { roles: ['admin'] },
  },
  {
    name: 'viewer',
    use: { ...devices['Desktop Chrome'] },
    metadata: { roles: ['viewer'] },
  },
  {
    name: 'vip',
    use: { ...devices['Desktop Chrome'] },
    metadata: { roles: ['vip'] },
  },
],

The config also starts both servers before the tests run.

webServer: [
  {
    command: 'npm run start:mockserver',
    url: 'http://127.0.0.1:3333',
    reuseExistingServer: !process.env.CI,
  },
  {
    command: 'npm run start:app',
    url: 'http://127.0.0.1:5173',
    reuseExistingServer: !process.env.CI,
  },
],

That means the test command is enough:

npm run test:e2e

The Role UI Test

The main test follows the same structure I use in larger Playwright frameworks:

keep page operations in page objects,
keep assertions in assertion helpers,
use test.step to make the business flow readable,
test both allowed and restricted role behavior.

The expectations stay close to the product behavior

const expectations = {
  admin: {
    title: 'Admin Operations Workspace',
    visible: ['admin-console', 'security-override', 'audit-log'],
    hidden: ['profile-search', 'vip-desk', 'concierge-notes'],
  },
  viewer: {
    title: 'Read-Only Viewer Workspace',
    visible: ['profile-search', 'read-only-dashboard', 'reports'],
    hidden: ['admin-console', 'security-override', 'vip-desk'],
  },
  vip: {
    title: 'VIP Support Workspace',
    visible: ['vip-desk', 'priority-override', 'concierge-notes'],
    hidden: ['admin-console', 'profile-search', 'audit-log'],
  },
};

Then each Playwright project adds its role header and verifies the UI through the page object.

test('renders the correct workspace and actions for the injected role',
  async ({ page }, testInfo) => {
    const [role] = testInfo.project.metadata.roles as AgentRole[];
    const expected = expectations[role];

    await test.step(`GIVEN the agent has the '${role}' role`, async () => {
      await mockAgentRoles(page, [role]);
    });

    await test.step('WHEN the operations console is opened', async () => {
      await operationsConsole.open();
      await operationsAssertions.assertConnected();
    });

    await test.step('THEN the roles from the mocked id_token are visible', async () => {
      await operationsAssertions.assertRoles([role]);
      await operationsAssertions.assertTokenContainsRole(role);
    });

    await test.step('AND the role-specific workspace is rendered', async () => {
      await operationsAssertions.assertWorkspaceTitle(expected.title);
    });

    await test.step('AND only the allowed actions are available', async () => {
      for (const action of expected.visible) {
        await operationsAssertions.assertActionVisible(action);
      }

      for (const action of expected.hidden) {
        await operationsAssertions.assertActionNotAvailable(action);
      }
    });
  },
);

This is the part that makes the implementation more than a mockserver example. The UI genuinely changes per role, and the test proves it through browser behavior.

Positive and Negative Role Checks

The role-specific tests are the public-demo equivalent of a real card or feature permission check.

test("Agent with only 'admin' role can access admin-only actions", async ({ page }) => {
  await test.step("GIVEN the agent has the 'admin' role", async () => {
    await mockAgentRoles(page, ['admin']);
  });

  await test.step('WHEN the operations console is opened', async () => {
    await operationsConsole.open();
    await operationsAssertions.assertConnected();
  });

  await test.step('THEN they can see the correct role against their account', async () => {
    await operationsAssertions.assertRoles(['admin']);
  });

  await test.step('AND admin-only actions are available', async () => {
    await operationsAssertions.assertActionVisible('admin-console');
    await operationsAssertions.assertActionVisible('security-override');
    await operationsAssertions.assertActionVisible('audit-log');
  });
});

And the restricted path:

test("Agent without 'admin' role cannot access admin-only actions", async ({ page }) => {
  await test.step("GIVEN the agent does not have the 'admin' role", async () => {
    await mockAgentRoles(page, ['viewer', 'vip']);
  });

  await test.step('WHEN the operations console is opened', async () => {
    await operationsConsole.open();
    await operationsAssertions.assertConnected();
  });

  await test.step('THEN they can see the correct roles against their account', async () => {
    await operationsAssertions.assertRoles(['viewer', 'vip']);
  });

  await test.step('AND admin-only actions are not available', async () => {
    await operationsAssertions.assertActionNotAvailable('admin-console');
    await operationsAssertions.assertActionNotAvailable('security-override');
    await operationsAssertions.assertActionNotAvailable('audit-log');
  });
});

This keeps the intent from the real-world spec: one scenario proves the role can use the feature, and another proves a user without the role is restricted.

Multiple Roles Are Supported

The suite also verifies role precedence.

test('supports multiple roles with admin taking precedence @roles', async ({ page }) => {
  await test.step("GIVEN the agent has 'viewer', 'vip', and 'admin' roles", async () => {
    await mockAgentRoles(page, ['viewer', 'vip', 'admin']);
  });

  await test.step('WHEN the operations console is opened', async () => {
    await operationsConsole.open();
    await operationsAssertions.assertConnected();
  });

  await test.step('THEN the admin workspace takes precedence', async () => {
    await operationsAssertions.assertRoles(['viewer', 'vip', 'admin']);
    await operationsAssertions.assertWorkspaceTitle('Admin Operations Workspace');
    await operationsAssertions.assertActionVisible('admin-console');
  });
});

This helps when real users can have more than one role.

Running the Project

Install dependencies:

npm install
npx playwright install chromium

Run the app manually:

npm run start:mockserver
npm run start:app

Open:

http://127.0.0.1:5173

Run the E2E suite:

npm run test:e2e

Why This Scales

This architecture scales because each part has a clear responsibility.

| Layer                   | Responsibility |
| -----------------------------------------------|
| Playwright project      | Chooses the role matrix |
| Playwright helper       | Adds role/config/error headers to mockserver requests |
| Token endpoint          | Converts agent-roles into signed token claims |
| Workspace endpoint      | Verifies token and returns role-specific UI data |
| Frontend                | Renders based on real API responses |
| Test assertion          | Verifies user-visible behavior |

The tests are deterministic, but they still exercise a realistic browser flow:

frontend calls backend,
backend returns token,
frontend uses token,
protected endpoint verifies token,
UI renders role-specific actions. That is much closer to production behavior than directly forcing frontend state.

Lessons Learned

Mock the boundary the app already trusts

For role-based applications, the auth token is often the right boundary. If roles live in the token in production, make the mockserver issue role-aware tokens in tests.

Keep Playwright helpers small

Helpers like mockAgentRoles, setFeatureFlags, and mockDownstreamServerError are simple enough to read in a spec but powerful enough to control backend behavior through the mockserver.

Make roles visible in the UI

For demos and debugging, showing the decoded roles and workspace actions makes failures easier to understand.

Test absence as well as presence

The tests assert that allowed actions are visible and disallowed actions do not exist. That prevents accidental permission leakage.

Keep public examples sanitized

Use local URLs, fake users, and fake profile data in public examples. The architecture matters; internal values do not.

Conclusion

Role-based E2E testing becomes scalable when Playwright sends lightweight test metadata and the mockserver owns backend behavior.

In this implementation:

The local app calls real mockserver endpoints.
Playwright continues selected mockserver requests with role/config/error headers.
The Koa mockserver signs those roles into an id_token.
The workspace endpoint verifies the token.
The UI renders different functionality for admin, viewer, and vip.
Playwright verifies those differences through real browser assertions. That gives you deterministic role coverage without losing the confidence of an end-to-end flow.

| Layer                         | Responsibility |
| :---                          | :---           |
| Playwright project            | Chooses the role matrix |
| Playwright helper             | Adds role/config/error headers to mockserver requests |
| Token endpoint                | Converts agent-roles into signed token claims |
| Workspace endpoint            | Verifies token and returns role-specific UI data |
| Frontend                      | Renders based on real API responses |
| Test assertion                | Verifies user-visible behavior |

Credits

Special thanks to Cara Townsend and the solution team for establishing the stubbed functional test environment itself, including the mockserver configuration, setup, and backend stubbing model that made this approach possible.

From there, our automation team scaled the pattern into existing Playwright test cases and expanded the role-based test matrix. Thanks also to Priyadarshini Ravichandran for helping shape and validate that implementation.

Adding live sync to a Notion finance template without Zapier, Make, or a backend published: false

Balaji K — Thu, 21 May 2026 00:20:26 +0000

How I turned WealthOS Lite into WealthOS Pro: a local-first Notion portfolio tracker with double-click sync for prices, SIP dates, and alerts.

tags: notion, javascript, productivity, showdev

A few weeks ago I wrote about shipping WealthOS Lite: a free Notion finance template that intentionally did less.

Two databases. A few formulas. No scripts. No API keys. No setup ceremony.

That post was about restraint.

This one is about the thing I deliberately left out of Lite:

live sync.

Most Notion finance templates run into the same wall eventually.

Manual tracking is clean, but stale.

Automation is useful, but the usual answer is:

connect Make.com
connect Zapier
pay monthly
create a bunch of scenarios
hope the integration does not break

That did not feel right for a personal finance system.

So for the Pro version, I tried a different architecture:

Keep Notion as the interface.

Keep the data in the user's workspace.

Run the sync locally on the user's own machine.

No hosted backend.

No Zapier.

No Make.

No subscription automation layer.

Just Notion + a small local Node.js sync app.

The constraint

I wanted WealthOS Pro to support a more complete portfolio:

stocks
mutual funds
ETFs
fixed deposits
gold
government bonds
retirement accounts
share plans
real estate
insurance
loans
financial goals
tax savings
alerts and reminders

But I did not want to turn it into a SaaS product.

That meant no central server storing user data.

The sync app had to run locally.

The user flow needed to be simple enough for non-developers:

1. Download ZIP
2. Duplicate Notion template
3. Double-click launch.command or launch.bat
4. Complete browser setup
5. Click Run Sync
No terminal commands.

That last part mattered more than I expected.

As developers, we are very comfortable saying:

node wealthos-sync.mjs
For normal users, that is already too much.

So the real product was not the script.

The product was making the script disappear.

The architecture
At a high level, WealthOS Pro looks like this:

WealthOS Notion Workspace
        |
        |  Notion API
        |
Local Sync App
        |
        |-- Yahoo Finance
        |-- Finnhub
        |-- mfapi.in
        |-- gold-api.com
The local app is a small Node.js bundle.

It reads a local .env file:

NOTION_API_KEY=...
MASTER_PORTFOLIO_ID=...
FINNHUB_KEY=...
Then it updates the Notion databases directly.

The important part: the data does not pass through my server.

There is no WealthOS cloud.

The user's portfolio lives in Notion, and the sync process runs on their computer.

Why not just build a SaaS?
I considered it.

A SaaS would be easier to monetize, easier to update centrally, and easier to control.

But personal finance data has a different trust profile.

I did not want users to ask:

Where is my portfolio data stored?

The answer should be simple:

In your Notion workspace and on your own machine.

That is also why the sync bundle is inspectable. The user can open the files, read the code, and see what is happening.

For this product, local-first felt more honest.

The single source of truth
The core Notion database is called Master Portfolio.

Every holding goes there.

Stocks, mutual funds, deposits, gold, loans, insurance, retirement accounts, share plans — all of them are rows in the same database.

That gives the system one reliable model:

Master Portfolio
├── Asset Name
├── Category
├── Sub-type
├── Country
├── Ticker
├── Units / Qty
├── Buy Price
├── Invested Amount
├── Current Price
├── Current Value
├── Gain / Loss
├── Return %
├── CAGR %
├── Next SIP Date
├── Last Updated
└── Risk Level
Different pages in Notion are just linked views of the same source.

That design decision avoided a trap I see in many complex Notion templates:

too many duplicated summary databases.

If you update one holding, every linked view, chart, formula, and dashboard can reflect it.

The sync app only needs to update the source rows.

How price sync works
For each row, the sync script checks the category and ticker.

For example:

NSE:RELIANCE  -> RELIANCE.NS
LSE:SHEL      -> SHEL.L
PA:MC         -> MC.PA
US stocks can use Finnhub if the user provides a free key.

Non-US stocks can fall back to Yahoo Finance.

Indian mutual funds use mfapi.in.

Gold uses a public gold price API.

The update is intentionally boring:

const props = {
"Current Price": { number: result.price },
"Last Updated": { date: { start: new Date().toISOString() } },
};

if (result.change != null) {
props["Day Change %"] = { number: result.change };
}

await updatePage(row.id, props);

The sync app does not try to own the portfolio logic.

It just updates the few fields that should come from external data.

Notion formulas handle the rest.

The double-click launcher
This was surprisingly important.

The folder contains:

launch.command   // macOS
launch.bat       // Windows
install-node.html
setup-ui.html
wealthos-app.mjs
wealthos-sync.mjs
sync-portfolio-metrics.mjs
sync-sip-dates.mjs
sync-alerts.mjs
On macOS, users double-click:

launch.command
On Windows:

launch.bat
The launcher checks whether Node.js is installed.

If not, it opens a local install guide.

If yes, it starts the local web setup app.

That web app opens in the browser and walks the user through:

Notion integration token
Master Portfolio database ID
optional Finnhub API key
first sync
The goal was to make the developer workflow feel like a normal desktop app.

The part that broke during testing
One bug showed up late.

Prices worked.

Portfolio metrics worked.

SIP dates worked.

But alerts were skipped.

The output looked like this:

Refreshing Alerts & Reminders…
Missing NOTION_API_KEY, MASTER_PORTFOLIO_ID, or ALERTS_REMINDERS_ID

Sync Complete
Prices: 12 updated
Metrics: refreshed
SIP dates: refreshed
Alerts: skipped
The bug was not in the Notion API.

It was in the product assumption.

The setup UI told users:

Other databases are auto-discovered.

But sync-alerts.mjs still required ALERTS_REMINDERS_ID.

That mismatch is exactly the kind of thing that only appears when you test like a buyer.

The fix was to let the alerts sync search for the database by title:

async function searchDatabaseByTitle(title) {
let cursor;
const wanted = title.toLowerCase();

do {
const body = {
query: title,
page_size: 100,
filter: { property: "object", value: "database" },
};

if (cursor) body.start_cursor = cursor;

const data = await api("POST", "/search", body);
const exact = data.results.find(
  (r) => titleOfDatabase(r).toLowerCase() === wanted
);

if (exact) return exact.id;

cursor = data.has_more ? data.next_cursor : null;

} while (cursor);

return null;
}



Now the sync auto-discovers:

Alerts & Reminders
Insurance Policies
Then it saves those IDs locally for future runs.

That turned this:

Alerts: skipped
into this:

Alerts: refreshed
Small fix, big confidence boost.

What the sync updates
One sync run refreshes:

stock prices
mutual fund NAVs
gold prices
portfolio metrics
next SIP dates
alerts for SIPs
loan EMI reminders
maturity reminders
insurance renewal reminders
The final output looks like this:

Sync Complete

Prices:     12 updated, 1 skipped, 0 failed
Metrics:    refreshed
SIP dates:  refreshed
Alerts:     refreshed
Time:       93.7s
That “boring” summary is the whole point.

A user should not need to understand the internals.

They should just know the data refreshed.

Why I kept it zero-dependency
The sync bundle uses Node.js 18+ and native fetch.

No npm install.

No package manager.

No dependency tree.

That was intentional.

For a developer tool, dependencies are normal.

For a ZIP file that a customer downloads and double-clicks, every dependency is another support ticket waiting to happen.

So the constraint became:

Can this run with only Node.js installed?
That made the code a little more manual in places, but the install story became much cleaner.

What I learned
1. Automation has to feel calm
The user does not care that the Notion API call succeeded.

They care that their dashboard now looks updated.

2. Local-first is a product feature
For finance tools, privacy is not just a technical detail. It is part of the value proposition.

3. Notion is great as the interface layer
I did not need to build dashboards, tables, filters, and charts from scratch. Notion already does that well.

The local app only fills the gaps Notion cannot handle alone.

4. Testing the ZIP matters
Running the code from the repo is not enough.

The real test is:

download ZIP
extract ZIP
double-click launcher
follow setup
run sync
check Notion
That is where the product actually exists.

Where this fits
WealthOS Lite is still the best starting point if you want a simple free finance tracker inside Notion.

WealthOS Pro is for people who want the bigger system:

more asset classes
local sync
setup guide
videos
alerts
multi-country portfolio structure

I packaged the Pro version here:

    
      
        
          balajibuilder.gumroad.com
          

        
      
    


The original open-source single-file finance app is here:


  
    
      
      
        balajiregt
       / 
        myFinance
      
    
    
      Self-hosted, single-file Indian portfolio tracker with AI insights, Gmail expense tracking
    
  
  
    

₹ FinFolio — Complete Indian Portfolio Tracker


Self-hosted, single-file, privacy-first portfolio tracker for Indian investors.

Track Stocks, Mutual Funds, FDs, RDs, SGB Gold, Physical Gold, Post Office schemes, Retirement (EPF/NPS), Real Estate, Insurance, Loans, Company Share Plans (ESPP/RSU/ESOP), and more — all from one dashboard with AI-powered insights. Auto-track expenses from bank emails via Gmail API. Proactive alerts via Telegram/WhatsApp.


Self-hosted means YOU own it. Fork this repo. Run it locally, or deploy to your own Fly.io instance. Cloud backup goes to your own Supabase instance. All data stays in your browser by default — no shared servers, no tracking, no accounts.






Why FinFolio?





























Problem

FinFolio Solution









Groww/Zerodha only show what you buy through them

Tracks ALL assets — broker, manual, physical





INDMoney wants your bank login

Zero server-side data — 100% localStorage





No app tracks physical gold in your bank locker

Physical gold tracker with storage locations + photo





…


  


  View on GitHub




And the earlier post about shipping WealthOS Lite is here:


  
  From a single-HTML-file finance app to a Notion template — lessons in shipping for users🥹


  
    
      
        

          
            
          
        
        
          
            
              Balaji K
            
            
              
                Balaji K
                
              
              
                
                  
                    
                      
                        
                      
                      Balaji K
                    
                  
                  
                    
                      Follow
                    
                  
                  
                
              
            

          
          May 7
        
      

    

    
      
        
          From a single-HTML-file finance app to a Notion template — lessons in shipping for users🥹
        
      
        
            #showdev
            #webdev
            #notion
            #productivity
        
      
        
          
            
              
                  
                    
                  
              
              1 reaction
            
          
            
              

              1 comment
            
        
        
          
            7 min read

Problem	FinFolio Solution
Groww/Zerodha only show what you buy through them	Tracks ALL assets — broker, manual, physical
INDMoney wants your bank login	Zero server-side data — 100% localStorage
No app tracks physical gold in your bank locker	Physical gold tracker with storage locations + photo

From a single-HTML-file finance app to a Notion template — lessons in shipping for users🥹

Balaji K — Thu, 07 May 2026 13:23:52 +0000

I've spent 12+ years writing automation systems for production platforms — test frameworks, API testing pipelines, the kind of code that runs invisibly so people upstream can ship faster.

A few weeks ago I shipped Finfolio — a single-HTML-file personal finance tracker. No backend. No sign-up. Your data never leaves your browser. It tracks every asset class an Indian investor actually holds — mutual funds, SGBs, FDs, ESPP/RSU, PPF, NPS, real estate — pulls live NAVs from AMFI, has Gmail OAuth to auto-categorize bank alerts into expenses, and has an AI layer that analyzes your portfolio with your own API key.

Repo here. MIT licensed. Free forever.

This weekend I shipped a Notion template that does ~30% of what Finfolio does. And honestly, I think it might be more useful for more people.
Here's why.

The lesson Finfolio taught me

Finfolio works. I use it every day. People who like full-control technical tools genuinely like it.

But here's what shipping it taught me: most people don't want a tool. They want a system.

Finfolio asks: "What's your AMFI scheme code? Do you want to enable Gmail OAuth? Where do you want to host this — Netlify, Vercel, fly.io, or just open it locally?" Those are perfect questions for engineers. They're terrible questions for my mother-in-law who just wants to see if her FDs and SIPs are doing OK.

The friction wasn't bugs or features. It was that the bar for entry was "be technically curious enough to enable Gmail OAuth." That's a small population.

So I asked a different question:

What if I rebuilt the core of Finfolio in a tool people already open every day, with a structure flexible enough to bend around their needs instead of mine?

For me — and a lot of knowledge workers — that tool is Notion.
So I started over with a hard constraint: two databases, three pages, and formulas that do all the work. No script to run. No API keys. No deployment step. Just duplicate and use.

The constraint became the feature.

The architecture: 2 databases, 3 pages

Finfolio has 12+ asset class trackers, an expense module, a goals module, an alerts hub, and AI-powered analysis. It's a suite.
The Notion version is the opposite. Aggressively minimal:
WealthOS Lite/
├── Dashboard (page)
│ ├── Net worth callout
│ └── Quick-start instructions
├── Portfolio (database)
│ ├── Asset Name (title)
│ ├── Category (select: Stocks, Mutual Fund, FD, Gold, etc)
│ ├── Invested Amount (number)
│ ├── Current Value (number)
│ ├── Gain/Loss (formula)
│ └── Return % (formula)
└── Budget (database)
├── Description (title)
├── Type (select: Income, Expense)
├── Category (select)
├── Amount (number)
└── Date (date)
That's the whole thing. Two databases, three pages, six properties on Portfolio, five on Budget.

This was the hardest design discipline in the entire project. I've already built the complete version — Finfolio knows about insurance renewals, EMI calculators, gold purity, post office schemes. Adding any of that to Lite would be one afternoon's work.

But here's what I learned: the Lite version of anything is usually the better product. People who get value from 2 databases will reach for the 12-database version when they're ready. People who never start because the template is overwhelming never come back.

The 3 formulas that do all the work

Notion formulas are limited in ways that frustrate engineers — no recursion, no loops, no array methods on relations. Coming from Finfolio's JavaScript codebase where I can do anything, this felt like a downgrade.
It isn't. For personal finance, you don't need any of that. You need three formulas.

Formula 1: Gain/Loss

prop("Current Value") - prop("Invested Amount")
That's it. The interesting part isn't the formula — it's that Notion recalculates it the moment you change either input. No sheet refreshes, no "press F9 to recalculate," no broken cell references when you reorder rows.
In Finfolio, I had to write reactive state management to make this work. Notion gave it to me for free.

Formula 2: Return %
if( prop("Invested Amount") > 0, round( ((prop("Current Value") - prop("Invested Amount")) / prop("Invested Amount")) * 10000 ) / 100, 0 )
Three things going on here:

Guard clause — if(prop("Invested Amount") > 0, ...) prevents division by zero when you create a new row before filling values.
The math — standard return percentage formula.
The round / 10000 * 100 dance — Notion's round() only rounds to integers. To get 2 decimal places, you multiply by 10000, round, divide by 100. Quirky but works.

The third bit is the kind of gotcha you only learn by hitting it. Notion's docs don't really call it out.

Formula 3: The conditional that handles asset-class quirks
This is the formula I'm proudest of, and it's worth sharing because it solves a common gotcha that bites every personal-finance template author.
When you add a Fixed Deposit to your portfolio, "Current Value" doesn't quite make sense — the value IS the invested amount until maturity. Same with cash holdings, recurring deposits, and bonds you're holding to maturity.

In Finfolio I solved this with conditional rendering and per-asset-class form fields. In Notion, one formula:
if( empty(prop("Current Value")), prop("Invested Amount"), prop("Current Value") )

Default to Invested Amount when Current Value is empty. Now FDs and cash holdings work correctly without users needing to type the same number twice. Small thing, big UX win.

The pattern from Finfolio that survived: smart defaults beat configuration every time.

The screenshot you don't see in product photos
Most Notion template marketing shows the dashboard view — clean, populated, looks great.

What it doesn't show is the Notion creator's secret weapon: linked database views.

The Portfolio database lives in one place. But on the Dashboard page, I render it again as:

A grouped view (by Category) with sum aggregations
A donut chart (Notion's chart blocks read directly from databases)
A filtered "top gainers" view

Same database, three different visualizations. Updating one row updates every view simultaneously, including the chart. No refresh, no sync, no broken state.

This is the same separation of concerns I'd apply to any system — model, view, controller. Notion just makes the "view" layer ridiculously easy.

In Finfolio I wrote ~400 lines of Chart.js and DOM manipulation to do what Notion gives me out of the box.

What I left out for v1 (and why)

This is where Finfolio's complexity contrasted hardest with the discipline a marketplace template requires.
I had a list of ~15 features I wanted to ship. I cut it to 6.
What didn't make it to Lite:

❌ Live price sync — needs a companion script. Out of scope for a free Notion-only template.
❌ Gmail OAuth for expenses — Finfolio's killer feature. Notion can't do OAuth flows. Will need a different solution.
❌ Multi-currency support — sounds simple, balloons fast. FX rates? Historical conversion? Display vs storage?
❌ Goals, SIP planner, tax modules — each is its own database. Pulled them out to keep Lite lite.
❌ AI analysis — Finfolio has it (bring your own key). Notion has Notion AI but the integration story for templates isn't clean yet.
❌ Mobile-optimized layouts — Notion handles this OK by default. Custom mobile design = duplicate page structures = maintenance burden.
❌ Auto-categorization — would need formulas with brittle string matching. Manual is fine for v1.

The rule I kept telling myself: "If I can't ship it cleanly in v1, it goes in the v2 backlog. Period."

Most template creators on the marketplace fail because they ship 40-feature behemoths nobody can figure out. The Finfolio version of WealthOS exists — it's the GitHub repo. The Notion version had to be different.

What "shipping" actually felt like

I want to be honest about this because dev.to readers are also makers, and we don't talk about it enough.
For Finfolio, I knew the workflow: write code, test, commit, push, deploy. Even when it took a weekend, the process was familiar.
For a Notion Marketplace template, the technical work was maybe 30% of the total time. The other 70% was things I genuinely didn't anticipate:

Naming things — went through 11 names before settling on WealthOS. Each rejection ("taken on Gumroad," "trademarked elsewhere," "weird connotation in Hindi") was its own time sink.
Designing covers and gallery images — Notion Marketplace requires specific dimensions (2048×1280 desktop, 750×1500 mobile) with strict safe-zone rules. Got rejected once for cropped content I thought looked fine.
Writing the description — version after version. The first draft was technical. The second was sales-y. The fifth one finally felt right.
Removing every promotional reference before submission. Notion's editorial guidelines flag templates that "primarily advertise paid products." Even one upgrade callout in the template body can trigger a rejection.
Setting up creator profile, banner, bio, social links — all the meta-stuff that has nothing to do with the product but determines whether anyone clicks.

Compared to Finfolio (where I just needed git push and a GitHub README), shipping a marketplace template is closer to launching a small product. The ratio of "actual building" to "preparing the building to be seen" was inverse to what I expected as an engineer.

What's next

WealthOS Lite is on Notion Marketplace as a free template — the foundation. Two databases, formulas, charts, your data stays in your workspace.

There's a Pro version I'm working on that connects back to the Finfolio architecture — a small Node.js companion app for live price syncing across stocks, mutual funds, and gold. Same "your data never leaves your machine" philosophy as Finfolio, but bridged into Notion. More on that when it's ready.

The bigger lesson from this whole exercise: the same problem can have radically different shapes depending on who you're solving it for. Finfolio is right for people who want full control. WealthOS Lite is right for people who want a clean system in a tool they already use. Neither is "better" — they're just for different people.

If you're building personal finance things, Notion templates, or anything else for non-technical users coming from technical roots, I'd love to compare notes.

Try WealthOS Lite (free): [https://stirring-heart-701.notion.site/WealthOS-Lite-34b3afb1ab1a81bf98f6e72a26551f50]
Finfolio (the original): github.com/balajiregt/myFinance
Building in public: @buildwithbalaji on X

I'm planning to write more about the engineering decisions behind shipping consumer-facing products as someone whose day job is automation infrastructure. If that's interesting, let me know what you'd want to read next.

✨ One HTML file. No backend. No sign-up. Your data never leaves your browser.

Balaji K — Fri, 01 May 2026 07:32:22 +0000

But here's what makes it different from the 50 other trackers out there:

→ Real-time broker sync for Mutual Funds Live NAV pulled from AMFI. Actual real-time sync with your broker holdings.

→ Gmail-synced expense tracking Connect Gmail (readonly OAuth) → finds your HDFC/ICICI/SBI bank alert emails → AI auto-parses merchant, amount, date, category → donut chart of where your money actually goes, plus budget vs actual comparison.

→ AI that analyses YOUR portfolio Bring your own API key. The AI looks at your actual holdings, your actual allocation, your actual gaps not some template "diversify more" response.

→ Export your financial profile to local Ollama Feed your complete snapshot to a local LLM. Your data stays on your machine. Run whatever analysis you want, privately.

→ Supabase cloud backup (optional, your own instance) Want sync across devices? Plug in your own Supabase. Don't want it? Everything works locally.

→ Reminders & Alerts hub Auto-generated from your insurance renewals, loan EMIs, FD maturities, SIP dates. Priority-based: overdue → urgent upcoming. No manual setup needed.

And it tracks everything Indian investors actually hold:
→ Mutual Funds, Stocks, ESPP/RSU/ESOP → Fixed & Recurring Deposits (multi-bank, maturity alerts) → Sovereign Gold Bonds (live spot price → INR) → Physical Gold (jewellery, coins purity, storage, photos) → Post Office schemes (PPF, SSY, NSC, MIS) → Insurance (term, health, endowment, vehicle — renewal tracking) → Loans (EMI tracking + prepayment calculator) → Real Estate (location, area, rental yield) → NPS, EPF, retirement planning

Dashboard gives you net worth across every asset class, allocation charts with diversification scoring, and dark/light theme with a clean Bootstrap UI.

Fork it. Deploy to Netlify/Vercel/fly.io. Or just double-click and open in your browser.

Next up: an agent layer that messages you on Telegram when your FD matures or your MF NAV drops 5%. More on that soon.

MIT Licensed. Free forever.

[https://www.linkedin.com/posts/kbalaji-kks_finfolio-activity-7447868974194720768-E3CY?utm_source=share&utm_medium=member_desktop&rcm=ACoAAA9LqPABRzpr8yo2ODcz6XIs182lmEqHPxY]

[https://github.com/balajiregt/myFinance]

DEV Community: Balaji K

Scaling Playwright E2E Tests with a Role-Aware Mockserver

Table of Contents:

A real working implementation with admin, viewer, and VIP UI flows:

Local Demo vs Real Stubbed Functional Environment

What We Are Building

Role Behavior in the UI

Mockserver: Auth-Style Backend Stub

Playwright Adds Role Headers to Mockserver Requests

Mockserver Signs Roles Into the ID Token

The App Uses the Token to Load Role-Specific Workspace Data

The Protected Workspace Endpoint Verifies the Token

Feature Flags Use the Same Header Pattern

Backend Error Scenarios Are Also Header-Driven

Playwright Projects Run the Role Matrix

The Role UI Test

Positive and Negative Role Checks

Multiple Roles Are Supported

Running the Project

Why This Scales

Lessons Learned

Mock the boundary the app already trusts

Keep Playwright helpers small

Make roles visible in the UI

Test absence as well as presence

Keep public examples sanitized

Conclusion

Credits

Adding live sync to a Notion finance template without Zapier, Make, or a backend published: false

How I turned WealthOS Lite into WealthOS Pro: a local-first Notion portfolio tracker with double-click sync for prices, SIP dates, and alerts.

The constraint

balajiregt / myFinance

Self-hosted, single-file Indian portfolio tracker with AI insights, Gmail expense tracking

₹ FinFolio — Complete Indian Portfolio Tracker

Why FinFolio?

From a single-HTML-file finance app to a Notion template — lessons in shipping for users🥹

From a single-HTML-file finance app to a Notion template — lessons in shipping for users🥹

The lesson Finfolio taught me

So I asked a different question:

The architecture: 2 databases, 3 pages

The 3 formulas that do all the work

What I left out for v1 (and why)

What "shipping" actually felt like

What's next

✨ One HTML file. No backend. No sign-up. Your data never leaves your browser.