svelte-declarative-testing 0.1.0

package/.prettierrc

@@ -0,0 +1,16 @@
+{
+  "useTabs": false,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "htmlWhitespaceSensitivity": "ignore",
+  "printWidth": 100,
+  "plugins": ["prettier-plugin-svelte"],
+  "overrides": [
+    {
+      "files": "*.svelte",
+      "options": {
+        "parser": "svelte"
+      }
+    }
+  ]
+}

package/README.md

@@ -0,0 +1,270 @@
+# svelte-declarative-testing
+
+One of the great things about Svelte is its compiler, producing a minimal
+runtime and providing a great, declarative way to build components.
+Unfortunately, unlike many other JavaScript frameworks, which use jsx or tagged
+template functions to render components in a declarative manner inside
+JavaScript files, Svelte has no such feature. Consider the following structure
+of composed components:
+
+```svelte
+<Popover>
+  <PopoverTrigger>Open Menu</PopoverTrigger>
+  <PopoverMenu>
+    <PopoverMenuItem href="/account">Account</PopoverMenuItem>
+    <PopoverMenuItem href="/logout">Log out</PopoverMenuItem>
+  </PopoverMenu>
+</Popover>
+```
+
+There _are_ existing ways to render this in your tests, but none of them are
+ergonomic. You can:
+
+- create a separate `.svelte` file for each configuration of your composed
+  components you want to test and pass that component to `render()`; or
+- create a single `.svelte` file and wrap all of your configurations in
+  `{#snippet <name>()}...{/snippet}`, along with a `{@render children()}`. You
+  export all the snippets and import them along with the default export, pass
+  the default export to `render(...)` and the snippet to the `children`
+  property; or
+- Use something like [vite-plugin-svelte-inline-component][vpsic] which allows
+  you to use tagged template literals along with some directive comments in your
+  test files.
+
+[vpsic]: https://github.com/hanielu/vite-plugin-svelte-inline-component
+
+Using this library, you can write your tests in Svelte syntax. This gives you
+much greater ergonomics and flexibility, especially for the above composition.
+Your tests can look like this:
+
+```svelte
+<!-- Popover.test.svelte -->
+<script>
+  import { Test, Check } from 'svelte-declarative-testing/vitest-browser-svelte';
+  import { Popover, PopoverTrigger, PopoverMenu, PopoverMenuItem } from './';
+</script>
+
+<Test it="opens the menu when the trigger is clicked">
+  <!-- children of the Test are rendered automatically -->
+  <Popover>
+    <PopoverTrigger>Open Menu</PopoverTrigger>
+    <PopoverMenu>
+      <PopoverMenuItem href="/account">Account</PopoverMenuItem>
+      <PopoverMenuItem href="/logout">Log out</PopoverMenuItem>
+    </PopoverMenu>
+  </Popover>
+
+  <!-- one or more test functions can be provided as checks -->
+  {#snippet checks()}
+    <Check
+      fn={async (screen) => {
+        expect(screen.getByRole('menu', { includeHidden: true })).not.toBeVisible();
+        await screen.getByRole('button', { name: 'Open Menu' }).click();
+        expect(screen.getByRole('menu')).toBeVisible();
+      }}
+    />
+  {/snippet}
+</Test>
+```
+
+## Installation
+
+Install as part of your project's `devDependencies` through your preferred
+package manager.
+
+```
+npm install --save-dev svelte-declarative-testing
+```
+
+## Setup
+
+There are 2 ways to activate your declarative svelte test files, using the
+provided Vite plugins or by importing them directly into another test file to
+mount them.
+
+### Using the plugins
+
+In order to work with the VSCode Vitest extension, 2 plugins are provided to
+instrument the source code. You will also need to make sure Vitest includes your
+test files:
+
+```javascript
+import svelteDeclarativeTesting from 'svelte-declarative-testing/vitest';
+
+export default defineConfig({
+  plugins: [
+    // ...
+
+    ...svelteDeclarativeTesting(),
+  ],
+
+  // ...
+
+  test: {
+    include: [
+      'src/**/*.svelte.{test,spec}.{js,ts}',
+
+      // Includes .test.svelte and .spec.svelte
+      'src/**/*.{test,spec}.svelte',
+    ],
+  },
+});
+```
+
+### Importing directly into your other tests
+
+> [!WARNING]
+> This approach will not allow you to trigger test runs using the Vitest
+> extension for VSCode. There may be some other side effects also.
+
+If you don't want to use the plugins, simply import your Svelte-syntax test
+files into your existing unit tests:
+
+```javascript
+// Popover.test.js
+import PopoverIntegrationTests from './Popover.test.svelte';
+import { render } from '@testing-library/svelte'; // or vitest-browser-svelte
+
+describe('Unit tests', () => {
+  // ... existing unit tests
+});
+
+describe('Integration tests', () => {
+  render(PopoverIntegrationTests);
+});
+```
+
+## Writing tests
+
+Writing tests is quite intuitive. It is a similar structure to JavaScript test
+files, with `describe()` and `test()` being replaced by `<Describe ...>` and
+`<Test ...>` respectively. Additionally, there is a `<Check>` function that
+allows you to provide the test functions.
+
+Convenience wrappers are provided for @testing-library/svelte and
+vitest-browser-svelte.
+
+```typescript
+import { Describe, Test, Check } from 'svelte-declarative-testing/testing-library';
+```
+
+```typescript
+import { Describe, Test, Check } from 'svelte-declarative-testing/vitest-browser-svelte';
+```
+
+Alternatively, you can import the core functions and provide a custom `render()`
+function to the `Test` component.
+
+```typescript
+import { Describe, Test, Check } from 'svelte-declarative-testing';
+```
+
+### `<Describe ...>`
+
+Wraps your tests in a suite, similare to `describe()`.
+
+```svelte
+<Describe label="My Integration Tests">
+```
+
+Inside `Describe`, tests go in a `tests()` snippet. Any other children will be
+rendered for each test.
+
+| Properties | Type       | Description                                                                           |
+| ---------- | ---------- | ------------------------------------------------------------------------------------- |
+| `label`    | `string`   | The descriptive label for the test suite                                              |
+| `children` | `Snippet`  | Any component(s) that you wish to render for the tests                                |
+| `tests`    | `Snippet`  | A snippet block containing one or more `<Test>` elements                              |
+| `skip`     | `any`      | Skips the suite if truthy, just like `describe.skip()`                                |
+| `only`     | `any`      | Only run this suite if truthy, just like `describe.only()`                            |
+| `todo`     | `any`      | Mark the suite as todo if truthy, just like `describe.todo()`                         |
+| `shuffle`  | `any`      | Mark the suite as todo if truthy, just like `describe.todo()`                         |
+| `skipIf`   | `function` | Skips the suite if the function returns a truthy value, just like `describe.skipIf()` |
+| `runIf`    | `function` | Runs the suite if the function returns a truthy value, just like `describe.runIf()`   |
+
+```svelte
+<Describe label="My Integration Tests">
+  <Button>My button</Button>
+
+  {#snippet tests()}
+    <Test it="renders an accessible button">
+      <!-- Test body goes here -->
+    </Test>
+
+    <Test it="does something when I click the button">
+      <!-- Test body goes here -->
+    </Test>
+  {/snippet}
+</Describe>
+```
+
+### `<Test ...>`
+
+Describes a test.
+
+```svelte
+<Test it="does what I expect it to do">
+```
+
+Inside `Test`, checks go in a `checks()` snippet. Any other children will be
+rendered for each test. If no other children are provided, the children of the
+parent `<Describe>` are rendered.
+
+| Properties | Type       | Description                                                                      |
+| ---------- | ---------- | -------------------------------------------------------------------------------- |
+| `it`       | `string`   | The description of the test                                                      |
+| `children` | `Snippet`  | Any component(s) that you wish to render for the test                            |
+| `checks`   | `Snippet`  | A snippet block containing one or more `<Check>` elements                        |
+| `skip`     | `any`      | Skips the test if truthy, just like `test.skip()`                                |
+| `only`     | `any`      | Only run this test if truthy, just like `test.only()`                            |
+| `todo`     | `any`      | Mark the test as todo if truthy, just like `test.todo()`                         |
+| `fails`    | `any`      | Passes the test on failure if truthy, just like `test.fails()`                   |
+| `skipIf`   | `function` | Skips the test if the function returns a truthy value, just like `test.skipIf()` |
+| `runIf`    | `function` | Runs the test if the function returns a truthy value, just like `test.runIf()`   |
+| `render()` | `function` | Provides a custom render function (not available on the wrapper components`      |
+
+```svelte
+<Test it="renders an accessible button">
+  <Button>My button</Button>
+
+  {#snippet checks()}
+    <Check fn={ /* ... */ } />
+    <Check fn={ /* ... */ } />
+  {/snippet}
+</Describe>
+```
+
+### `<Check ...>`
+
+Provides a test function.
+
+```svelte
+<Check fn={() => expect(1 + 1).toBe(2)} />
+```
+
+You can provide as many checks as you like and they will run sequentially.
+
+| Properties | Type       | Description                                        |
+| ---------- | ---------- | -------------------------------------------------- |
+| `fn`       | `function` | A function to be executed as part of the test body |
+
+```svelte
+<Test it="renders an accessible button">
+  <Button>My button</Button>
+
+  {#snippet checks()}
+    <Check fn={({queryByRole}) => {
+      expect(queryByRole("button")).toBeIntheDocument();
+    }/>
+  {/snippet}
+</Describe>
+```
+
+## Credits
+
+This is not a new idea and was originally posited by [@7nik][7nik] and
+[@paoloricciuti][paol] on the Svelte bug tracker. Thanks also to @sheremet-va,
+who assisted with the Vitest test detection plugins.
+
+[7nik]: https://github.com/sveltejs/svelte/issues/14791#issuecomment-3166064732
+[paol]: https://github.com/sveltejs/svelte/issues/14791#issuecomment-3166186575

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "svelte-declarative-testing",
+  "version": "0.1.0",
+  "description": "A way to mount your Svelte test components declaratively",
+  "type": "module",
+  "module": "src/index.js",
+  "main": "src/index.js",
+  "exports": {
+    "./testing-library": {
+      "types": "./src/components/testing-library/index.d.ts",
+      "default": "./src/components/testing-library/index.js"
+    },
+    "./vitest-browser-svelte": {
+      "types": "./src/components/vitest-browser-svelte/index.d.ts",
+      "default": "./src/components/vitest-browser-svelte/index.js"
+    },
+    "./internal": {
+      "types": "./src/components/internal/index.d.ts",
+      "default": "./src/components/internal/index.js"
+    },
+    "./vitest": {
+      "types": "./src/plugins/index.d.ts",
+      "default": "./src/plugins/vitest.js"
+    }
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "svelte",
+    "vitest",
+    "test",
+    "testing-library"
+  ],
+  "author": "Andy Earnshaw",
+  "license": "ISC",
+  "dependencies": {
+    "magic-string": "^0.30.21",
+    "ts-essentials": "^10.1.1",
+    "zimmerframe": "^1.1.4"
+  },
+  "devDependencies": {
+    "eslint": "^9.39.2",
+    "prettier": "^3.8.1",
+    "prettier-plugin-svelte": "^3.4.1"
+  },
+  "peerDependencies": {
+    "@testing-library/svelte": "^5.3.1",
+    "svelte": "^5.49.0",
+    "vitest": "^4.0.18",
+    "vitest-browser-svelte": "^2.0.2"
+  },
+  "peerDependenciesMeta": {
+    "@testing-library/svelte": {
+      "optional": true
+    },
+    "vitest-browser-svelte": {
+      "optional": true
+    }
+  }
+}

package/src/components/core/Check.svelte

@@ -0,0 +1,11 @@
+<script lang="ts">
+  /**@import { CheckProps } from './' */
+  import { getAddCheck } from './context.js';
+
+  /**@type {CheckProps} */
+  const { fn } = $props();
+
+  $effect(() => {
+    getAddCheck()?.(fn);
+  });
+</script>

package/src/components/core/Describe.svelte

@@ -0,0 +1,37 @@
+<script>
+  /** @import { DescribeProps } from './' */
+  import { describe } from 'vitest';
+  import { setAddTest, setSuiteRenderSnippet } from './context.js';
+
+  /**@type {DescribeProps}*/
+  const { label, todo, only, skip, skipIf, runIf, children, tests } = $props();
+
+  /**@type {((result: unknown) => void | Promise<void>)[]} */
+  const testFns = [];
+
+  setAddTest((fn) => {
+    testFns.push(fn);
+  });
+
+  // svelte-ignore state_referenced_locally
+  setSuiteRenderSnippet(children);
+
+  $effect(() => {
+    const describeFn = () => {
+      if (skip) return describe.skip;
+      if (skipIf) return describe.skipIf(skipIf());
+      if (todo) return describe.todo;
+      if (only) return describe.only;
+      if (runIf) return describe.runIf(runIf());
+      return describe;
+    };
+
+    describeFn()(label, async () => {
+      for (const test of testFns) {
+        await test();
+      }
+    });
+  });
+</script>
+
+{@render tests()}

package/src/components/core/Test.svelte

@@ -0,0 +1,56 @@
+<script>
+  /**@import { TestProps } from './index.js' */
+  import { test } from 'vitest';
+  import { getAddTest, setAddCheck, getSuiteRenderSnippet } from './context.js';
+  import Wrapper from './Wrapper.svelte';
+
+  /**@type {TestProps} */
+  const { it, fails, todo, only, skip, skipIf, runIf, children, checks, render } = $props();
+
+  /**@type {((result: unknown) => void | Promise<void>)[]} */
+  const checkFns = [];
+
+  const addTest = getAddTest();
+
+  const suiteRenderSnippet = getSuiteRenderSnippet();
+
+  setAddCheck((fn) => {
+    checkFns.push(fn);
+  });
+
+  const setupTest = () => {
+    const testFn = () => {
+      if (skip) return test.skip;
+      if (skipIf) return test.skipIf(skipIf());
+      if (todo) return test.todo;
+      if (only) return test.only;
+      if (fails) return test.fails;
+      if (runIf) return test.runIf(runIf());
+      return test;
+    };
+
+    testFn()(it, async () => {
+      const result = await render(Wrapper, { children: children ?? suiteRenderSnippet });
+
+      try {
+        if (!checkFns.length) {
+          throw new Error(`No checks were registered for test: "${it}"`);
+        }
+
+        for (const check of checkFns) {
+          await check(result);
+        }
+      } finally {
+        result.unmount();
+      }
+    });
+  };
+
+  addTest?.(setupTest);
+
+  $effect(() => {
+    if (!addTest) setupTest();
+  });
+</script>
+
+{@render checks()}

package/src/components/core/Wrapper.svelte

@@ -0,0 +1,8 @@
+<script>
+  /**@import type { Snippet } from 'svelte';*/
+
+  /**@type {{ children: Snippet }}*/
+  const { children } = $props();
+</script>
+
+{@render children()}

package/src/components/core/context.ts

@@ -0,0 +1,7 @@
+import { createContext, Snippet } from 'svelte';
+
+export const [getAddTest, setAddTest] = createContext<(fn: () => void | Promise<void>) => void>();
+
+export const [getAddCheck, setAddCheck] = createContext<(fn: () => void | Promise<void>) => void>();
+
+export const [getSuiteRenderSnippet, setSuiteRenderSnippet] = createContext<Snippet | undefined>();

package/src/components/core/index.d.ts

@@ -0,0 +1,39 @@
+import type { Snippet, Component } from 'svelte';
+import { XOR } from 'ts-essentials';
+
+export type ModifierProps = XOR<
+  /* These are all mutually exclusive */
+  { only: boolean },
+  { todo: boolean },
+  { skip: boolean },
+  { skipIf: () => unknown },
+  { runIf: () => unknown }
+>;
+
+export type DescribeProps =
+  | {
+      label: string;
+      children?: Snippet;
+      tests: Snippet;
+    }
+  | ModifierProps;
+
+export type BaseTestProps =
+  | {
+      it: string;
+      children?: Snippet;
+      checks: Snippet;
+    }
+  | XOR<ModifierProps, { fails: boolean }>;
+
+export type TestProps = BaseTestProps & {
+  render: (result: unknown) => void | Promise<void>;
+};
+
+export type CheckProps = {
+  fn: (result: unknown) => void | Promise<void>;
+};
+
+export declare const Describe: Component<DescribeProps>;
+export declare const Test: Component<TestProps>;
+export declare const Check: Component<CheckProps>;

package/src/components/core/index.js

@@ -0,0 +1,3 @@
+export { default as Describe } from './Describe.svelte';
+export { default as Test } from './Test.svelte';
+export { default as Check } from './Check.svelte';

package/src/components/testing-library/Check.svelte

@@ -0,0 +1,9 @@
+<script>
+  /** @import { CheckProps } from './' */
+  import { Check as CoreCheck } from '../core';
+
+  /**@type {CheckProps}*/
+  const props = $props();
+</script>
+
+<CoreCheck {...props} />

package/src/components/testing-library/Test.svelte

@@ -0,0 +1,11 @@
+<script>
+  /**@import { BaseTestProps } from '../core' */
+
+  import { Test as CoreTest } from '../core';
+  import { render } from '@testing-library/svelte';
+
+  /**@type {BaseTestProps}*/
+  const props = $props();
+</script>
+
+<CoreTest {render} {...props} />

package/src/components/testing-library/index.d.ts

@@ -0,0 +1,14 @@
+import { RenderResult } from '@testing-library/svelte';
+import { Component } from 'svelte';
+import type { BaseTestProps, DescribeProps } from '../core';
+
+export type CheckFn = (result: RenderResult<Component<any, any>>) => void | Promise<void>;
+
+export type CheckProps = {
+  fn: CheckFn;
+};
+
+export { DescribeProps };
+export declare const Describe: Component<DescribeProps>;
+export declare const Test: Component<BaseTestProps>;
+export declare const Check: Component<CheckProps>;

package/src/components/testing-library/index.js

@@ -0,0 +1,3 @@
+export { Describe } from '../core';
+export { default as Test } from './Test.svelte';
+export { default as Check } from './Check.svelte';

package/src/components/vitest-browser-svelte/Check.svelte

@@ -0,0 +1,9 @@
+<script>
+  /**@import { CheckProps } from './' */
+  import { Check as CoreCheck } from '../core';
+
+  /**@type {CheckProps}*/
+  const props = $props();
+</script>
+
+<CoreCheck {...props} />

package/src/components/vitest-browser-svelte/Test.svelte

@@ -0,0 +1,11 @@
+<script>
+  /**@import { BaseTestProps } from '../core' */
+
+  import { Test as CoreTest } from '../core';
+  import { render } from 'vitest-browser-svelte';
+
+  /**@type {BaseTestProps}*/
+  const props = $props();
+</script>
+
+<CoreTest {render} {...props} />

package/src/components/vitest-browser-svelte/index.d.ts

@@ -0,0 +1,14 @@
+import { RenderResult } from 'vitest-browser-svelte';
+import { Component } from 'svelte';
+import type { BaseTestProps, DescribeProps } from '../core';
+
+export type CheckFn = (result: RenderResult<Component<any, any>>) => void | Promise<void>;
+
+export type CheckProps = {
+  fn: CheckFn;
+};
+
+export { DescribeProps };
+export declare const Test: Component<BaseTestProps>;
+export declare const Check: Component<CheckProps>;
+export declare const Describe: Component<DescribeProps>;

package/src/components/vitest-browser-svelte/index.js

@@ -0,0 +1,3 @@
+export { Describe } from '../core';
+export { default as Test } from './Test.svelte';
+export { default as Check } from './Check.svelte';

package/src/index.js

@@ -0,0 +1,2 @@
+export { default as Test } from './core';
+export { default as Check } from './core';

package/src/plugins/index.d.ts

@@ -0,0 +1,3 @@
+// TODO fix type
+declare const getPlugins: () => any[];
+export default getPlugins;

package/src/plugins/vitest.js

@@ -0,0 +1,93 @@
+/** @import type { Plugin } from 'vitest/config' */
+import { parse } from 'svelte/compiler';
+import { walk } from 'zimmerframe';
+import MagicString from 'magic-string';
+
+const pre = () =>
+  /**@type {Plugin}*/ ({
+    name: 'transform-svelte-declarative-test',
+    enforce: 'pre',
+    transform(code, id) {
+      if (!/\.(?:test|spec)\.svelte$/.test(id)) {
+        return;
+      }
+
+      const s = new MagicString(code);
+      const ast = parse(code);
+      walk(
+        ast.html,
+        {},
+        {
+          InlineComponent(node, { visit }) {
+            if (node.name === 'Test') {
+              for (const attr of node.attributes) {
+                if (attr.name === 'it') {
+                  const name =
+                    attr.value?.[0]?.data?.replace(/"/g, '\\"') ?? '(dynamically named test)';
+
+                  s.appendLeft(
+                    attr.start,
+                    `data-test-code={function () { test("${name}", () => {}) }} `,
+                  );
+                }
+              }
+
+              return;
+            } else if (node.name === 'Describe') {
+              for (const attr of node.attributes) {
+                if (attr.name === 'label') {
+                  const name =
+                    attr.value?.[0]?.data?.replace(/"/g, '\\"') ?? '(dynamically named test suite)';
+
+                  s.appendLeft(
+                    attr.start,
+                    `data-describe-code={function () { describe("${name}", () => {}) }} `,
+                  );
+                }
+              }
+
+              for (const child of node.children) {
+                if (child.type === 'SnippetBlock') {
+                  visit(child);
+                }
+              }
+            }
+          },
+          SnippetBlock(node, { visit }) {
+            for (const child of node.children) {
+              if (child.type === 'InlineComponent') {
+                visit(child);
+              }
+            }
+          },
+        },
+      );
+
+      console.log(s.toString());
+      return { code: s.toString(), map: s.generateMap({ hires: true }) };
+    },
+  });
+
+const post = () =>
+  /**@type {Plugin}*/ ({
+    name: 'transform-svelte-declarative-test',
+    enforce: 'post',
+    transform(code, id) {
+      if (!/\.(?:test|spec)\.svelte$/.test(id)) {
+        return;
+      }
+
+      const s = new MagicString(code);
+      const componentName = id.split('/').pop()?.split('.').slice(0, -1).join('_');
+      s.append(`
+          import { mount } from 'svelte';
+          mount(${componentName}, { target: document.body });
+        `);
+
+      return { code: s.toString(), map: s.generateMap({ hires: true }) };
+    },
+  });
+
+export default function getPlugins() {
+  return [pre(), post()];
+}