@atelier-wb/svelte
v0.12.0-beta.4
Published
Svelte bindings to test your svelte components
Downloads
82
Readme
Atelier - Svelte bindings
Weclome to the Atelier!
This package contains bindings for Svelte UI framework. They allow you to test your Svelte components in isolation.
- Getting started
- Tweak properties
- Events reporting
- Slots and side markup
- Setup and teardown code
- Tool boxes
- Examples
Getting started
Create a file with .tools.svelte
extension.
<script>
import { Tool } from '@atelier-wb/svelte'
import MyComponent from './MyComponent.svelte'
</script>
<Tool
name="My Awesome Component"
component={MyComponent}
/>
That's it! Now configure Atelier with Vite, and browse to http://localhost:3000/atelier: you'll see your component in action!
Each tool operates on one of your component, and can:
- controls its properties
- listen to its events
Tweak properties
To enable property control, just initialize them in your tool's props
:
<Tool
name="My Awesome Component"
component={MyComponent}
props={{ prop1: 'my component first prop', prop2: 42 }}
/>
Atelier will automatically creates controls in the "Properties" tab so you can change your property values.
It supports numbers, booleans, strings, arrays and objects.
Functions and Svelte stores can not be configured from Atelier.
Events reporting
To listen to your event properties (either DOM native or custom), write their names in an events
array:
<Tool
name="My Awesome Component"
component={MyComponent}
events={['click', 'custom-event']}
/>
Once they'll be triggered, Atelier will show the time, event name and details in the "Events" tab.
It is automatically cleared when opening a different tool, and there is a button to do it manually.
Note: you can also "programmaticaly" record an event:
<script>
import { Tool, recordEvent } from '@atelier-wb/svelte'
import MyComponent from './MyComponent.svelte'
</script>
<Tool
name="My Awesome Component"
props={{
myComponentFunctionProp: () => recordEvent('programmatic-event', 'event arg 1', 'arg could be anything')
}}
component={MyComponent}
/>
Slots and side markup
If your component uses slots, or needs some companion markup, you can use <Tool>
as templates:
<Tool
name="My Awesome Component"
props={{ prop1: 'my component first prop', prop2: 42 }}
let:props
let:handleEvent
>
<div>You can put any markup before the component.<div>
<MyComponent
{...props}
on:click={handleEvent}
on:custom-event={handleEvent}
>
<span>this goes into YOUR component</span>
</MyComponent>
<div>You can also have markup after.<div>
</Tool>
Please note key differences:
tool does not need
component={MyComponent}
any moretool has
let:props
, and your component has{...props}
. This allows Atelier to configure properties even if your component is "burried" into the templatetool has
let:handleEvent
, and your component binds it to specific event. This allows Atelier to receive any event you'd like.
If you want to tweak properties, don't forget to initialize them on Tool
: otherwise Atelier will not generates the corresponding controls.
Setup and teardown code
If you need to run code every time your tool loads, you can use setup
function:
<Tool
name="My Awesome Component"
component={MyComponent}
props={{ prop1: 'my awesome prop' }}
setup={async ({ name, props }) => {
return newProps
}}
/>
The setup
function:
could either be synchronous or asynchronous.
receives a single object parameter, with the
name
andprops
keys (the ones you passed to<Tool/>
)can return new
props
for your component. Ifsetup()
returns nothing,props
from the markup will be used.
You can also use teardown
function:
<Tool
name="My Awesome Component"
component={MyComponent}
teardown={async name => {}}
/>
The teardown
function:
could either be synchronous or asynchronous.
receives the component
name
(the one you passed to<Tool/>
)
Tool boxes
You can add as many <Tool/>
in the same file as you want.
But there may be a lot of code duplication!
<ToolBox/>
can solve this issue:
<ToolBox name="My Awesome Component" component={MyComponent}>
<Tool name="Primary" props={{ color: 'red', primary: true }} />
<Tool name="Secondary" props={{ color: 'blue' }} />
</ToolBox>
This helps you easily test variations of the same component.
Important highlights:
a tool's full name is its tool box's name + its own name. In the example above:
My Awesome Component / Primary
a tool box supports exactly the same properties as tool, with some specificities:
name
are concatenated, as explained above.tool's
component
override tool box.props
are merged.events
are merged.tool box's
setup()
runs before the tool'ssetup()
. The result of the primer becomesprops
parameter of the later.tool box's
teardown()
runs after the tool'steardown()
.
tool box do not support templates.
Examples
Now that you know everything, you may want some real examples.
You'll find some in Atelier's UI tests