docs(examples): add examples to repository

Author: mcous

.all-contributorsrc

@@ -109,7 +109,7 @@
       "name": "Michael Cousins",
       "avatar_url": "https://avatars.githubusercontent.com/u/2963448?v=4",
       "profile": "https://michael.cousins.io/",
-      "contributions": ["code"]
+      "contributions": ["code", "doc", "ideas", "maintenance", "test"]
     }
   ],
   "contributorsPerLine": 7,

.github/workflows/release.yml

@@ -37,8 +37,9 @@ jobs:
           - { svelte: '5', node: '16' }
           - { svelte: '5', node: '18' }
         include:
-          # We only need to lint once, so do it on latest Node and Svelte
+          # Only lint and test examples on latest Node and Svelte
           - { svelte: '5', node: '22', check: 'lint' }
+          - { svelte: '5', node: '22', check: 'test:examples' }
           # Run type checks in latest applicable Node
           - { svelte: '3', node: '20', check: 'types:legacy' }
           - { svelte: '4', node: '22', check: 'types:legacy' }

CONTRIBUTING.md

@@ -77,10 +77,10 @@ npm run all:legacy
 
 ### Docs
 
-Use the `toc` script to ensure the README's table of contents is up to date:
+Use the `docs` script to ensure the README's table of contents is up to date:
 
 ```shell
-npm run toc
+npm run docs
 ```
 
 Use `contributors:add` to add a contributor to the README:

README.md

@@ -12,9 +12,10 @@
 
 <p>Simple and complete Svelte testing utilities that encourage good testing practices.</p>
 
-[**Read The Docs**][stl-docs] | [Edit the docs][stl-docs-repo]
+[**Read The Docs**][stl-docs] | [Edit the docs][stl-docs-repo] | [Examples](./examples)
 
 <!-- prettier-ignore-start -->
+
 [![Build Status][build-badge]][build]
 [![Code Coverage][coverage-badge]][coverage]
 [![version][version-badge]][package]
@@ -29,7 +30,9 @@
 [![Watch on GitHub][github-watch-badge]][github-watch]
 [![Star on GitHub][github-star-badge]][github-star]
 [![Tweet][twitter-badge]][twitter]
+
 <!-- prettier-ignore-end -->
+
 </div>
 
 <hr />
@@ -63,9 +66,6 @@
 
 ## Table of Contents
 
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-
 - [The Problem](#the-problem)
 - [This Solution](#this-solution)
 - [Installation](#installation)
@@ -78,8 +78,6 @@
   - [❓ Questions](#-questions)
 - [Contributors](#contributors)
 
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
 ## The Problem
 
 You want to write maintainable tests for your [Svelte][svelte] components.
@@ -217,8 +215,11 @@ instead of filing an issue on GitHub.
 Thanks goes to these people ([emoji key][emojis]):
 
 <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
+
 <!-- prettier-ignore-start -->
+
 <!-- markdownlint-disable -->
+
 <table>
   <tbody>
     <tr>
@@ -240,12 +241,13 @@ Thanks goes to these people ([emoji key][emojis]):
       <td align="center" valign="top" width="14.28%"><a href="https://techblog.babyl.ca/"><img src="https://avatars.githubusercontent.com/u/19954?v=4?s=100" width="100px;" alt="Yanick Champoux"/><br /><sub><b>Yanick Champoux</b></sub></a><br /><a href="https://github.com/testing-library/svelte-testing-library/commits?author=yanick" title="Code">💻</a></td>
     </tr>
     <tr>
-      <td align="center" valign="top" width="14.28%"><a href="https://michael.cousins.io/"><img src="https://avatars.githubusercontent.com/u/2963448?v=4?s=100" width="100px;" alt="Michael Cousins"/><br /><sub><b>Michael Cousins</b></sub></a><br /><a href="https://github.com/testing-library/svelte-testing-library/commits?author=mcous" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://michael.cousins.io/"><img src="https://avatars.githubusercontent.com/u/2963448?v=4?s=100" width="100px;" alt="Michael Cousins"/><br /><sub><b>Michael Cousins</b></sub></a><br /><a href="https://github.com/testing-library/svelte-testing-library/commits?author=mcous" title="Code">💻</a> <a href="https://github.com/testing-library/svelte-testing-library/commits?author=mcous" title="Documentation">📖</a> <a href="#ideas-mcous" title="Ideas, Planning, & Feedback">🤔</a> <a href="#maintenance-mcous" title="Maintenance">🚧</a> <a href="https://github.com/testing-library/svelte-testing-library/commits?author=mcous" title="Tests">⚠️</a></td>
     </tr>
   </tbody>
 </table>
 
 <!-- markdownlint-restore -->
+
 <!-- prettier-ignore-end -->
 
 <!-- ALL-CONTRIBUTORS-LIST:END -->

eslint.config.js

@@ -75,7 +75,10 @@ export default tseslint.config(
     files: ['**/*.svelte'],
     rules: {
       'svelte/no-unused-svelte-ignore': 'off',
-      'unicorn/filename-case': ['error', { case: 'pascalCase' }],
+      'unicorn/filename-case': [
+        'error',
+        { cases: { kebabCase: true, pascalCase: true } },
+      ],
       'unicorn/no-useless-undefined': 'off',
     },
   },

examples/basic/basic.svelte

@@ -0,0 +1,13 @@
+<script>
+  let { name } = $props()
+
+  let showGreeting = $state(false)
+
+  const onclick = () => (showGreeting = true)
+</script>
+
+<button {onclick}>Greet</button>
+
+{#if showGreeting}
+  <p>Hello {name}</p>
+{/if}

examples/basic/basic.test.js

@@ -0,0 +1,26 @@
+import { render, screen } from '@testing-library/svelte'
+import { userEvent } from '@testing-library/user-event'
+import { expect, test } from 'vitest'
+
+import Subject from './basic.svelte'
+
+test('no initial greeting', () => {
+  render(Subject, { name: 'World' })
+
+  const button = screen.getByRole('button', { name: 'Greet' })
+  const greeting = screen.queryByText(/hello/iu)
+
+  expect(button).toBeInTheDocument()
+  expect(greeting).not.toBeInTheDocument()
+})
+
+test('greeting appears on click', async () => {
+  const user = userEvent.setup()
+  render(Subject, { name: 'World' })
+
+  const button = screen.getByRole('button')
+  await user.click(button)
+  const greeting = screen.getByText(/hello world/iu)
+
+  expect(greeting).toBeInTheDocument()
+})

examples/basic/readme.md

@@ -0,0 +1,68 @@
+# Basic
+
+This basic example demonstrates how to:
+
+- Pass props to your Svelte component using [render()]
+- [Query][] the structure of your component's DOM elements using screen
+- Interact with your component using [@testing-library/user-event][]
+- Make assertions using expect, using matchers from
+  [@testing-library/jest-dom][]
+
+[query]: https://testing-library.com/docs/queries/about
+[render()]: https://testing-library.com/docs/svelte-testing-library/api#render
+[@testing-library/user-event]: https://testing-library.com/docs/user-event/intro
+[@testing-library/jest-dom]: https://github.com/testing-library/jest-dom
+
+## Table of contents
+
+- [`basic.svelte`](#basicsvelte)
+- [`basic.test.js`](#basictestjs)
+
+## `basic.svelte`
+
+```svelte file=./basic.svelte
+<script>
+  let { name } = $props()
+
+  let showGreeting = $state(false)
+
+  const onclick = () => (showGreeting = true)
+</script>
+
+<button {onclick}>Greet</button>
+
+{#if showGreeting}
+  <p>Hello {name}</p>
+{/if}
+```
+
+## `basic.test.js`
+
+```js file=./basic.test.js
+import { render, screen } from '@testing-library/svelte'
+import { userEvent } from '@testing-library/user-event'
+import { expect, test } from 'vitest'
+
+import Subject from './basic.svelte'
+
+test('no initial greeting', () => {
+  render(Subject, { name: 'World' })
+
+  const button = screen.getByRole('button', { name: 'Greet' })
+  const greeting = screen.queryByText(/hello/iu)
+
+  expect(button).toBeInTheDocument()
+  expect(greeting).not.toBeInTheDocument()
+})
+
+test('greeting appears on click', async () => {
+  const user = userEvent.setup()
+  render(Subject, { name: 'World' })
+
+  const button = screen.getByRole('button')
+  await user.click(button)
+  const greeting = screen.getByText(/hello world/iu)
+
+  expect(greeting).toBeInTheDocument()
+})
+```

examples/binds/bind.svelte

@@ -0,0 +1,5 @@
+<script>
+  let { value = $bindable('') } = $props()
+</script>
+
+<input type="text" bind:value />

examples/binds/bind.test.js

@@ -0,0 +1,24 @@
+import { render, screen } from '@testing-library/svelte'
+import { userEvent } from '@testing-library/user-event'
+import { expect, test } from 'vitest'
+
+import Subject from './bind.svelte'
+
+test('value binding', async () => {
+  const user = userEvent.setup()
+  let value = ''
+
+  render(Subject, {
+    get value() {
+      return value
+    },
+    set value(nextValue) {
+      value = nextValue
+    },
+  })
+
+  const input = screen.getByRole('textbox')
+  await user.type(input, 'hello world')
+
+  expect(value).toBe('hello world')
+})

examples/binds/no-bind.svelte

@@ -0,0 +1,9 @@
+<script>
+  let { value, onInput } = $props()
+
+  const oninput = (event) => {
+    onInput(event.target.value)
+  }
+</script>
+
+<input type="text" {value} {oninput} />

examples/binds/readme.md

@@ -0,0 +1,82 @@
+# Binds
+
+Two-way data binding using [bindable() props][] is difficult to test directly.
+It's usually easier to structure your code so that you can test user-facing
+results, leaving the binding as an implementation detail.
+
+However, if two-way binding is an important developer-facing API of your
+component, you can use setters to test your binding.
+
+[bindable() props]: https://svelte.dev/docs/svelte/$bindable
+
+## Table of contents
+
+- [`bind.svelte`](#bindsvelte)
+- [`bind.test.js`](#bindtestjs)
+- [Consider avoiding binding](#consider-avoiding-binding)
+
+## `bind.svelte`
+
+```svelte file=./bind.svelte
+<script>
+  let { value = $bindable('') } = $props()
+</script>
+
+<input type="text" bind:value />
+```
+
+## `bind.test.js`
+
+```svelte file=./bind.test.js
+import { render, screen } from '@testing-library/svelte'
+import { userEvent } from '@testing-library/user-event'
+import { expect, test } from 'vitest'
+
+import Subject from './bind.svelte'
+
+test('value binding', async () => {
+  const user = userEvent.setup()
+  let value = ''
+
+  render(Subject, {
+    get value() {
+      return value
+    },
+    set value(nextValue) {
+      value = nextValue
+    },
+  })
+
+  const input = screen.getByRole('textbox')
+  await user.type(input, 'hello world')
+
+  expect(value).toBe('hello world')
+})
+```
+
+## Consider avoiding binding
+
+Before embarking on writing tests for bindable props, consider avoiding
+`bindable()` entirely. Two-way data binding can make your data flows and state
+changes difficult to reason about and test effectively. Instead, you can use
+value props to pass data down and callback props to pass changes back up to the
+parent.
+
+> Well-written applications use bindings very sparingly — the vast majority of
+> data flow should be top-down --
+> <cite>[Rich Harris](https://github.com/sveltejs/svelte/issues/10768#issue-2181814844)</cite>
+
+For example, rather than using a `bindable()` prop, use a value prop to pass the
+value down and callback prop to send changes back up to the parent:
+
+```svelte file=./no-bind.svelte
+<script>
+  let { value, onInput } = $props()
+
+  const oninput = (event) => {
+    onInput(event.target.value)
+  }
+</script>
+
+<input type="text" {value} {oninput} />
+```

examples/contexts/context.svelte

@@ -0,0 +1,14 @@
+<script>
+  import { getContext } from 'svelte'
+
+  let { label } = $props()
+
+  const messages = getContext('messages')
+</script>
+
+<div role="status" aria-label={label}>
+  {#each messages.current as message (message.id)}
+    <p>{message.text}</p>
+    <hr />
+  {/each}
+</div>

examples/contexts/context.test.js

@@ -0,0 +1,24 @@
+import { render, screen } from '@testing-library/svelte'
+import { expect, test } from 'vitest'
+
+import Subject from './context.svelte'
+
+test('notifications with messages from context', async () => {
+  const messages = {
+    get current() {
+      return [
+        { id: 'abc', text: 'hello' },
+        { id: 'def', text: 'world' },
+      ]
+    },
+  }
+
+  render(Subject, {
+    context: new Map([['messages', messages]]),
+    props: { label: 'Notifications' },
+  })
+
+  const status = screen.getByRole('status', { name: 'Notifications' })
+
+  expect(status).toHaveTextContent('hello world')
+})