[RFC] Args Mocking via ArgTypes

[vanessayuenn]

Status: Proposed
Champion: @kasperpeulen

---

Authors: @tmeasday @kasperpeulen

Summary

This RFC proposes a solution to providing mocked arg values for callbacks that doesn’t require inference, at the cost of being manually configured. Ideally:

• Ergonomic (quick to write)
• Fully typed
• Backwards compatible (with inferred args mocks)
• Forwards compatible (future non-prop-based arg mocking)

Problem Statement

Automatic arg mocking is a neat feature that we shipped in Storybook 6.5. We automatically analyze your components, figure out function inputs, and then automatically generate actions that get passed to your stories. From this, you get:

• Automatic logging in the actions panel for debugging
• Automatic spies that can be asserted in play function tests (e.g. expect(onClick).toHaveBeenCalled())

Unfortunately, this “magical” feature has led to a number of unsolved problems that complicate/block key initiatives. If we had an ergonomic way for users to specify these arg mocks as part of their story definition, we could unblock all of these other projects.

Non-goals

A fully fleshed out solution for current non-features such as network and import mocking (although let’s consider them).

Implementation

Streamlined argType API, special SBScalarType for actions

const meta: Meta<typeof Button> = {
  argTypes: {
    count: 'number', // string based short hand for { type: 'number' }
    onClick: 'action', // special short hand for "mocked function"
  },
}

• Pros: quite simple
• Cons: what do we call it? Are there other special types we should be adding (e.g. color?)

Prior Art

Current ArgType TS type:

export interface InputType {
  name?: string;
  description?: string;
  defaultValue?: any;
  type?: SBType | SBScalarType['name'];
  if?: Conditional;
  [key: string]: any;
}

Current API for mocking a single arg:

const meta: Meta<typeof Button> = {
  argTypes: { onClick: { action: 'clicked' } },
}

Current automatic actions mocking API

const preview: Preview = {
  parameters: {
    actions: { argTypesRegex: '^on.*' },
  },
};

Deliverables

1. Update the type definition of ArgType to allow strings, update normalizeInputType function to handle shorthand
   • Expand to { type: ‘function’, returnType: ‘undefined’ } (Or should it just expand to { type: 'event' }?)
   • Update action + interaction addons to detect such argTypes.
2. Document this approach, remove all reference to inference based approaches, except in READMEs.
3. Update TS story definition to make args with either shorthand or longhand “event” argType definition optional.

Risks

No response

Unresolved Questions

No response

Alternatives considered / Abandoned Ideas

Inference based on prop types

The current system uses inference on the name of the arg and a configured parameter. It’s zero config as the arg name is inferred. However it both (a) requires inference, and (b) is a challenge for TS as the parameter can be changed and is not possible to access from TS.

An alternative proposal would be to infer the type of the arg and if it is a non-valued function, to automatically mock it (as justified elsewhere).

The downside of this approach is that it still needs inference, and in fact it requires a more reliable inference than just detecting the name.

Other ways of manually specifying args

Keep matching on name, ask users to name their mocked args

const meta: Meta<typeof Button> = {
  argTypes: { onClick: {} // no details required },
  parameters: { action: { argTypesRegex: '^on.*' } }, // as before
}

• Pros: very simple
• Cons: doesn’t solve TS problem, sort of “magical” and not obvious why they need to do it.

Just encourage people to use the current API

const meta: Meta<typeof Button> = {
  argTypes: { onClick: { action: 'clicked' } },
}

• Pros: no work! Just documentation + typescript updates.
• Cons: Why do you have to name the action? Could be more ergonomic.

Function type based matching without inference

const meta: Meta<typeof Button> = {
  // Currently our function type doesn't vary at all, we might need to add more annotations
  argTypes: { onClick: { type: { 'function', returnType: 'undefined' } },
}

• Pros: Can implement function type based system below and fallback to user annotations when inference is not available.
• Cons: Could be confusing about when it is necessary (when is inference available)? Why not use more ergonomic API above?

Parameter based?

const meta: Meta<typeof Button> = {
	parameters: {
    actionArgs: ['onClick', 'onBar'],
  }
}

zod or a similar structured type library

import { z } from 'zod';

const meta: Meta<typeof Button> = {
  component: C,
  // argTypes: { onClick: z.function() } 
}

• Pros: Ergonomic, popular w/ large community (5m weekly npm dls), don’t reinvent the wheel
• Cons: Another dependency/integration point for SB

[vanessayuenn]

@kasperpeulen is writing a new proposal that shall supersede this RFC. The new one should be posted early next week. Closing this discussion for now.