https://github.com/h2xd/exposition
Structure to explain the who, what and where of the API mocking process
https://github.com/h2xd/exposition
dx mocks testing typescript vuejs
Last synced: about 2 months ago
JSON representation
Structure to explain the who, what and where of the API mocking process
- Host: GitHub
- URL: https://github.com/h2xd/exposition
- Owner: h2xd
- License: mit
- Created: 2022-04-24T16:40:01.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2023-04-25T21:14:37.000Z (about 2 years ago)
- Last Synced: 2025-04-18T09:01:45.261Z (about 2 months ago)
- Topics: dx, mocks, testing, typescript, vuejs
- Language: TypeScript
- Homepage: https://h2xd.github.io/exposition/
- Size: 1.81 MB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Exposition
Structure to explain the who, what and where of the API mocking process
The ambition is to enhance the creation, usage and the overall experience of API mocking.
Documentation •
Ping me on Twitter
## Motivation
The goal of this project is to provide perfect developer experience, when it comes to API mocking.
The reason is that API mocking with a large subset of different variations / results is really hard,
and I saw a lot of project skipping tests because even thinking about the amount of work and the debugging
later on is insane. _Okay! Okay! I will stop. Here is a candy to calm down._ 🍬
**This library is written with the thought that devs never want to leave their IDE and love to fiddle around with code first. Therefore, you can find a lot of examples and descriptions in TSDoc.**
## Install dependencies
Here are three commands for the most used package managers.
_I'll be biased and promote my favorite one first._
```sh
pnpm add -D @exposition/core
```
```sh
yarn add -D @exposition/core
```
```sh
npm install -D @exposition/core
```
## Create an exposition 📙
```ts
const exposition = new Exposition({
stage: {
options: ['🐛 Small', '🦋 Big']
}
} as const)
```
You can also cluster scenarios into groups by defining further objects inside the config as stated in the below example.
_The last option MUST have an `options` key for internal type inference._
```ts
const exposition = new Exposition({
user: {
age: {
options: ['under 18 🐣', '18 🐓', 'over 18 🦖']
},
avatar: {
options: ['no avatar 💬', 'image 🤳']
},
auth: {
options: ['valid ✅', 'deny ❌']
},
rights: {
users: {
create: {
options: ['yes ✅', 'no ❌']
},
read: {
options: ['yes ✅', 'no ❌']
},
update: {
options: ['yes ✅', 'no ❌']
},
delete: {
options: ['yes ✅', 'no ❌']
}
}
}
}
} as const)
```
### Config
The first parameter is a simple record that will define the Schema of your `Exposition`
instance. Feel free to name your keys that describe your `Scenario` in the best possible way.
Also, the first index of the `options` array will be set as the `initialValue` of the `Scenario`.
### Options
You can overwrite the default settings of `Exposition` with the second parameter.
| setting | description | example |
| -------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `active` | Signal all integrations that they should stop their actions | [`@exposition/integrations/msw`](https://h2xd.github.io/exposition/integrations/msw.html) will reset all handler if this option is set to `false` |
| `restoreState` | Signal all integrations that they should prevent all state restoration handler | [`@exposition/integrations/vue-devtools`](https://h2xd.github.io/exposition/integrations/vue-devtools.html) will not interact with the `localStorage` if this option is set to `false` |
```ts
const exposition = new Exposition(
{
// ... your config
},
{
settings: {
active: false,
restoreState: false,
}
}
)
```
## Interact with the state
You can use the following commands to interact with your defined `Scenario` elements:
| command | type | action |
|-----------------| -------- |------------------------------------------------------------------------|
| `values` | `getter` | return the current `Scenario` values |
| `initialValues` | `getter` | similar to `values` but will return the initialValue of the `Scenario` |
| `update` | `method` | update one or multiple of your `Scenario` values |
| `reset` | `method` | reset one or multiple `Scenario` elements to their `initialValue` |
| `init` | `method` | signal all integrations that you are finished with your setup |
| `getState` | `method` | get current enriched exposition config state |
There are also commands to read and change the state of the overall `Exposition` settings:
| command | type | action |
| ---------------- | -------- | -------------------------------------------- |
| `settings` | `getter` | get the currently set settings |
| `updateSettings` | `method` | update one or multiple `Exposition` settings |
## Listen on events
You can write handler to react to the following events:
| event | timing | extras |
| ---------------- | ------------------------------------------ | ------------------------ |
| `reset` | when the `reset` method is called | |
| `update` | when the `update` method is called | |
| `initialized` | when the `init` method is called | will only be called once |
| `updateSettings` | when the `updateSettings` method is called | |
The event handler will also contain the current `Exposition.values` and `Exposition.settings`.
```ts
const exposition = new Exposition({
stage: {
options: ['🐛 Small', '🦋 Big']
}
} as const)
exposition.on('update', (values, settings) => {
console.log(values)
})
exposition.update({ stage: '🦋 Big' })
// will trigger the console.log
// console.log(values) -> { "stage": "🦋 Big" }
```
## Add an integration
Mock Service Worker is the primary integration and even the reason
for this library. Therefore, I highly recommend to start with the [msw setup guide](https://h2xd.github.io/exposition/cookbook/setup-msw.html) first.
You can also create your own integration that levels on the above `on` events.
A guide how to write a custom integration will follow.
For now, you can check out the implementation of [`msw`](https://github.com/h2xd/exposition/blob/main/packages/integrations/msw/functions/createMswIntegration.ts)
## Packages
- [🌱 @exposition/core](https://github.com/h2xd/exposition/tree/main/packages/core) — _main functionality_
- [🧩 @exposition/integrations](https://github.com/h2xd/exposition/tree/main/packages/integrations) — _extensions for developer experience_
- [🧰 @exposition/core](https://github.com/h2xd/exposition/tree/main/packages/sdk) — _utils to build custom integrations or other exposition based function_
- [🌐 @exposition/web](https://github.com/h2xd/exposition/tree/main/packages/web) — (NOT PUBLISHED) _utils to interact with web apis like localStorage or the window object_
## Misc
- [🏗 Board](https://github.com/users/h2xd/projects/2)