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')
+})