testdrive-jsui/tutorials/Tutorial 1 Hello World.md

Tutorial 1: Hello World!

Let’s walk through your first HelloWorld component built with TestDrive-UI.

This will demonstrate the full workflow: 👉 requirement → test → implementation → run → refinement.

---

🧱 1. Project setup

If you haven’t already:

unzip testdrive-ui.zip
cd testdrive-ui
npm install

Now you’re ready to create your first component.

---

🧩 2. Create a component folder

mkdir src/components/hello-world

Inside it, you’ll have:

hello-world/
├── hello-world.js
├── hello-world.test.js
└── hello-world.stories.js

---

✏️ 3. Step 1 — Write the requirement

“When <hello-world> is rendered, it should display the text Hello World! and clicking the element should show an alert.”

That’s your behavioral spec — the “why” that drives the test.

---

🧪 4. Step 2 — Write the test first

src/components/hello-world/hello-world.test.js

import "./hello-world.js";

describe("<hello-world>", () => {
  it("renders the correct greeting", () => {
    const el = document.createElement("hello-world");
    document.body.appendChild(el);

    const content = el.shadowRoot.textContent;
    expect(content).to.include("Hello World!");
  });

  it("triggers an alert on click", () => {
    const el = document.createElement("hello-world");
    document.body.appendChild(el);

    let alerted = false;
    window.alert = () => (alerted = true);

    const div = el.shadowRoot.querySelector("div");
    div.click();

    expect(alerted).to.be.true;
  });
});

Run this test now:

npm test

Both tests will fail initially — perfect, that’s the TDD start.

---

💡 5. Step 3 — Implement the component

src/components/hello-world/hello-world.js

import { LitElement, html, css } from "lit";

export class HelloWorld extends LitElement {
  static styles = css`
    div {
      font-family: system-ui, sans-serif;
      font-size: 1.5rem;
      color: #007acc;
      padding: 1rem;
      text-align: center;
      cursor: pointer;
      user-select: none;
    }
    div:hover {
      color: #005fa3;
    }
  `;

  render() {
    return html`<div @click=${this._onClick}>Hello World!</div>`;
  }

  _onClick() {
    alert("Hello from TestDrive-UI!");
  }
}

customElements.define("hello-world", HelloWorld);

Run the tests again:

npm test

✅ Both should now pass.

---

⚡ 6. Step 4 — Preview it in the browser

Add it to your index.html:

<script type="module" src="./components/hello-world/hello-world.js"></script>
<hello-world></hello-world>

Then run:

npm run dev

Open http://localhost:5173 → You’ll see your clickable Hello World! component rendered live.

---

🧭 7. Step 5 — Visual story (optional)

src/components/hello-world/hello-world.stories.js

import "./hello-world.js";

export default {
  title: "UI/Hello World",
};

export const Default = () => `<hello-world></hello-world>`;

Once you add Storybook to the scaffold later, this file will automatically generate a visual preview card.

---

✅ 8. What you achieved

• Created an independent UI component with Lit
• Wrote deterministic tests with jsdom + Mocha
• Verified behavior automatically
• Previewed visually via Vite

This loop is your core TestDrive-UI workflow:

spec → test → implement → run → refine

xxx