Onboard an existing app

Every command on this page was run against a real repository: cypress-io/cypress-realworld-app — a React and Express banking app with 33 existing Cypress specs. Clone it next to your SDODS checkout and you can follow along exactly, or swap in your own app and read the same output shape.

git clone --depth 1 https://github.com/cypress-io/cypress-realworld-app.git ../cypress-realworld-app

The five minutesCopy Anchor Link

1. AnalyzeCopy Anchor Link

sdods analyze ../cypress-realworld-app

The analyzer opens files and never writes one. The header is the summary: package manager, frameworks with a confidence score, the test-id attribute counted in the source, the authentication libraries it recognised, and the base URLs it inferred.

Then the route inventory, taken from the router and the server, with the file and line each one came from:

Existing tests are inventoried too, including which locator styles they use — the number that decides how much of a migration you are looking at:

The checklist turns all of that into things to do, each with the command that does it:

2. Read the proposalCopy Anchor Link

Below the analysis, analyze prints the project it would write: the slug, the layers, the test-id attribute, the routes it will address by name, the tag taxonomy, and one module per route group.

# Generated by `sdods analyze`. Review routes, modules and auth before committing.
slug: rwa-bank
name: RWA Bank
layers: [ui, api, hybrid]
testIdAttribute: data-test
routes:
  signin: /signin
  signup: /signup
  personal: /personal
  contacts: /contacts
tags:
  suites: [smoke, regression, sanity]
  roles: [standard, admin]

Read three things before you apply it:

3. ApplyCopy Anchor Link

sdods analyze ../cypress-realworld-app --apply --project rwa-bank --name "RWA Bank"

projects/rwa-bank/
├── sdods.project.yaml          # layers, routes, modules, tags, test-id attribute
├── envs/local.yaml             # base URLs, headers, user pool size
├── features/                   # 14 starter features: one per route group, one per API group
│   ├── signin/signin.feature
│   └── login/login-api.feature
├── pages/HomePage.ts           # a page object to grow
├── steps/                      # fixtures, auth and project steps
├── data/common/users.csv       # the user pool, empty of secrets
├── har/  ·  recorded/          # ready for `sdods har record` and `sdods record`
└── README.md

The generated scenarios are health checks, not aspirations. A page scenario asserts the route renders; an endpoint scenario asserts the endpoint answers with a non-5xx status inside five seconds:

@ui @signin
Feature: Signin pages

  @smoke
  Scenario: The signin page loads
    Given I navigate to the "signin" page
    Then the page URL should contain "/signin"

Lint them straight away — it is instant, and it is the difference between a typo now and a red suite in ten minutes:

sdods lint -p rwa-bank
# ✔ 14 feature file(s) linted, no findings

4. Correct the guessesCopy Anchor Link

Static analysis reads what the source says, and a running application sometimes disagrees. On this repository five things needed a human, and each one is a single line:

api:
  baseUrl: http://localhost:3001 # analyze guessed 3000; the backend listens on 3001

auth:
  strategy: form
  storageState: true
  form:
    loginPath: /signin
    usernameSelector: '[data-test="signin-username"] input'
    passwordSelector: '[data-test="signin-password"] input'
    submitSelector: '[data-test="signin-submit"]'
    readyUrl: /

5. First runCopy Anchor Link

Start the application, then run the two layers.

# terminal 1 — the application under test
cd ../cypress-realworld-app && yarn dev

# terminal 2 — SDODS
sdods run -p rwa-bank -e local -l api                        # endpoints, no browser
sdods run -p rwa-bank -e local -l ui -b chromium -t @smoke   # pages, in chromium

The API layer passes on the first attempt, because an endpoint either answers or it does not:

The UI layer does not, and that is the point of running it:

All five failures are the same failure:

Give it one. The pool users live in data/common/users.csv, auth capture signs one in once and stores the state, and the tag @user:standard makes a scenario start from that state:

sdods auth capture -p rwa-bank -e local        # → projects/rwa-bank/.auth/local/standard-0.json

  @smoke @user:standard
  Scenario: The personal page loads
    Given I navigate to the "personal" page
    Then the page URL should contain "/personal"

Then look at what the run recorded:

sdods report --last --open     # HTML report and the run dashboard
sdods trace --last             # the Playwright trace of any failing step

What the suite covers, and what it does notCopy Anchor Link

sdods coverage -p rwa-bank --routes

coverage joins the route and endpoint inventory with the scenarios you have, split by suite tag, so the gap is a number rather than a feeling.

Coverage for rwa-bank
routes 4/4  endpoints 9/9  roles 0/2  scenarios 13  @smoke=13

Everything answers, and nothing is yet checked as a particular person: roles 0/2 is the whole story of a freshly onboarded project.

The generated suite gets you to “everything answers”. The next three things are worth doing in this order: a real assertion per role, @regression scenarios for the flows that make money, and data that comes from a fixture rather than from whatever the database happens to hold. The workshop walks all three on this same repository.

Bringing existing tests alongCopy Anchor Link

analyze copies existing Playwright specs into recorded/imported/ unless you pass --no-import-specs. Cypress specs are inventoried rather than copied, because their API differs — the migration path is to record the flow once and convert it:

sdods record -p rwa-bank -e local --url signin --name signin-flow
sdods record convert projects/rwa-bank/recorded/signin-flow.spec.ts

record convert asks your configured model adapter to turn the recording into a proposal: a feature file plus the steps it needs, using role and test-id locators instead of the CSS chains the old specs relied on. Nothing is applied automatically — you review it with sdods proposals list and accept it when you agree. Without a model key, --dry-run prints the plan and --adapter fake produces the shape. Guides → Migrating covers the whole path.

Start from scratch insteadCopy Anchor Link

When there is no application to read — a service that does not exist yet, or a repository you cannot clone — project create scaffolds the same shape by hand:

sdods project create my-app \
  --ui-url http://localhost:3000 \
  --api-url http://localhost:3000/api \
  --env local

It writes the YAML, an environment, fixtures, an authentication stub, a page object, health features and a data folder. See the project command reference.

What analyze detectsCopy Anchor Link

Next stepsCopy Anchor Link

• The workshop — the same repository, feature by feature, in one sitting
• Projects and environments
• Your first API test