One JSON File, Two Jobs: Interactive Tours That Also Run as Playwright Tests

#testing #javascript #productivity #webdev

The Problem Nobody Talks About

You've built an onboarding flow. Your product team wants users to experience it live. Your QA team wants automated tests covering the same flow. So what do you do?

You write the tour for users. Then you write a separate Playwright test. Then you maintain both. When the tour changes, you update the test. When the test breaks, you fix it independently. Eventually, they drift. Your test passes but users see something different. Your tour is broken but the test never caught it.

This is one of those problems that feels unsolvable until you realize it doesn't have to exist.

What If They Were the Same Thing?

What if you defined your onboarding flow once, as a single JSON file, and it automatically worked as both?

Set it to "mode": "both" and it plays as an interactive tour for real users. The same file, the same data, runs as a Playwright regression test in your CI pipeline. No separate test suite. No drift. No duplication.

Here's what that looks like:

{
  "id": "user-signup-tour",
  "mode": "both",
  "steps": [
    {
      "selector": "button[data-test='signup-email']",
      "title": "Enter your email",
      "description": "Type your work email to get started",
      "action": "type",
      "value": "user@example.com"
    },
    {
      "selector": "button[data-test='submit']",
      "title": "Create your account",
      "action": "click"
    },
    {
      "selector": ".dashboard-header",
      "title": "Welcome to your dashboard",
      "description": "This is where you'll spend most of your time",
      "assertion": "visible"
    }
  ]
}

When a user first signs up, they see the tour. It highlights each step, explains what to do, and guides them through your product.

When your CI pipeline runs, the same file becomes a test. It finds those selectors, performs those actions, checks those assertions. If anything breaks, you know before it reaches production.

Why This Matters

Test maintenance is a drag. Most teams write tests, then watch them slowly break as the product changes. Developers get tired of updating them. Tests become outdated. You stop trusting them.

Onboarding tours have the same problem in reverse. You build a beautiful guided experience. Then it drifts from reality because nobody's validating it automatically.

When they're the same thing, everything snaps into focus. You change the flow once. Both the user experience and the test update together. The test validates that users see what they're supposed to see. The tour validates that your test actually reflects reality.

Running It

Locally, you can run the same file as a Playwright test without any extra setup. In CI, it's just another test job. No special framework. No duplicate code. One source of truth.

Add onboarding analytics on top and you see exactly where users drop off or need help. User feedback tools capture confusion in real time. Your tour, test, and analytics all speak the same language.

The Ripple Effect

Once you stop maintaining separate test suites, your whole workflow changes. You ship faster because you're not juggling two codebases. Your QA doesn't argue with product about what the tour should do, because it's validated by tests. Your developers trust that if a test passes, users actually see what they're supposed to see.

It's not magic. It's just removing the duplication that should never have existed in the first place.

You can try this approach free at gettrailguide.com. MIT-licensed for runtime, or upgrade to Pro at $49/month if you want the full feature set.

DEV Community