test: component description conformance test

build/gulp/tasks/test-unit.ts

@@ -0,0 +1,38 @@
+import { parallel, series, task } from 'gulp'
+import { argv } from 'yargs'
+
+import sh from '../sh'
+
+// ----------------------------------------
+// Jest
+// ----------------------------------------
+const jest = ({ watch = false } = {}) => cb => {
+  process.env.NODE_ENV = 'test'
+
+  // in watch mode jest never exits
+  // let the gulp task complete to prevent blocking subsequent tasks
+  const command = [
+    'jest --coverage',
+    ...(watch ? ['--watchAll'] : []),
+    ...(argv.runInBand ? ['--runInBand'] : []),
+    ...(argv.maxWorkers ? [`--maxWorkers=${argv.maxWorkers}`] : []),
+  ].join(' ')
+  return sh(command)
+}
+
+task('test:jest:pre', () => sh('yarn satisfied'))
+
+task(
+  'test:jest:setup',
+  series('test:jest:pre', parallel('build:docs:docgen', 'build:docs:component-menu-behaviors')),
+)
+
+task('test:jest', jest())
+task('test:jest:watch', jest({ watch: true }))
+
+// ----------------------------------------
+// Tests
+// ----------------------------------------
+
+task('test', series('test:jest:setup', 'test:jest'))
+task('test:watch', series('test:jest:setup', parallel('test:jest:watch', 'watch:docs')))

gulpfile.ts

@@ -12,6 +12,7 @@ require('./build/gulp/tasks/docs')
 require('./build/gulp/tasks/generate')
 require('./build/gulp/tasks/screener')
 require('./build/gulp/tasks/git')
+require('./build/gulp/tasks/test-unit')
 require('./build/gulp/tasks/test-projects')
 
 // global tasks

package.json

@@ -32,11 +32,11 @@
     "prestart": "yarn satisfied --fix yarn",
     "start": "gulp --series dll docs",
     "satisfied": "satisfied --skip-invalid --ignore \"^typescript$\"",
-    "pretest": "yarn satisfied && gulp build:docs:docgen && gulp build:docs:component-menu-behaviors",
-    "test": "cross-env NODE_ENV=test jest --coverage",
+    "pretest": "yarn satisfied && gulp --series build:docs:docgen build:docs:component-menu-behaviors",
+    "test": "gulp test",
     "test:visual": "gulp screener",
     "test:projects:cra-ts": "gulp test:projects:cra-ts",
-    "test:watch": "yarn test --watchAll",
+    "test:watch": "gulp test:watch",
     "generate:component": "gulp generate:component"
   },
   "lint-staged": {

src/components/Button/ButtonGroup.tsx

@@ -27,7 +27,7 @@ export interface ButtonGroupProps {
 }
 
 /**
- * A button group.
+ * A button group presents multiple related actions.
  */
 class ButtonGroup extends UIComponent<Extendable<ButtonGroupProps>, any> {
   public static displayName = 'ButtonGroup'

src/components/Chat/ChatItem.tsx

@@ -22,6 +22,9 @@ export interface ChatItemProps {
   variables?: ComponentVariablesInput
 }
 
+/**
+ * A chat item represents a single event in a chat.
+ */
 class ChatItem extends UIComponent<Extendable<ChatItemProps>, any> {
   static className = 'ui-chat__item'
 

src/components/Chat/ChatMessage.tsx

@@ -46,6 +46,9 @@ export interface ChatMessageProps {
   variables?: ComponentVariablesInput
 }
 
+/**
+ * A chat message represents a single statement communicated to a user.
+ */
 class ChatMessage extends UIComponent<Extendable<ChatMessageProps>, any> {
   static className = 'ui-chat__message'
 

src/components/Label/Label.tsx

@@ -39,7 +39,7 @@ export interface LabelProps {
 }
 
 /**
- * A label displays content classification
+ * A label is used to classify content.
  */
 class Label extends UIComponent<Extendable<LabelProps>, any> {
   static displayName = 'Label'

src/components/Layout/Layout.tsx

@@ -37,6 +37,9 @@ export interface LayoutProps {
   variables?: ComponentVariablesInput
 }
 
+/**
+ * A layout is a utility for arranging the content of a component.
+ */
 class Layout extends UIComponent<Extendable<LayoutProps>, any> {
   static className = 'ui-layout'
 

src/components/List/List.tsx

@@ -34,6 +34,9 @@ export interface ListProps extends FocusContainerProps<ShorthandValue> {
   variables?: ComponentVariablesInput
 }
 
+/**
+ * A list displays a group of related content.
+ */
 class List extends UIComponent<Extendable<ListProps>, FocusContainerState> {
   static displayName = 'List'
 

src/components/List/ListItem.tsx

@@ -33,6 +33,9 @@ export interface ListItemState {
   isHovering: boolean
 }
 
+/**
+ * A list item contains a single piece of content within a list.
+ */
 class ListItem extends UIComponent<Extendable<ListItemProps>, ListItemState> {
   static create: Function
 

src/components/Menu/Menu.tsx

@@ -39,6 +39,9 @@ export interface MenuProps {
   variables?: ComponentVariablesInput
 }
 
+/**
+ * A menu displays grouped navigation actions.
+ */
 class Menu extends AutoControlledComponent<Extendable<MenuProps>, any> {
   static displayName = 'Menu'
 

src/components/Menu/MenuItem.tsx

@@ -44,6 +44,9 @@ export interface MenuItemState {
   [IsFromKeyboard.propertyName]: boolean
 }
 
+/**
+ * A menu item is an actionable navigation item within a menu.
+ */
 class MenuItem extends UIComponent<Extendable<MenuItemProps>, MenuItemState> {
   static displayName = 'MenuItem'
 

src/components/RadioGroup/RadioGroupItem.tsx

@@ -45,6 +45,7 @@ export interface RadioGroupItemState {
 }
 
 /**
+ * A single radio with a radio group.
  * @accessibility
  * Radio items need to be grouped in RadioGroup component to correctly handle accessibility.
  */

src/components/Segment/Segment.tsx

@@ -12,6 +12,9 @@ export interface SegmentProps {
   variables?: ComponentVariablesInput
 }
 
+/**
+ * A segment is used to create a grouping of related content.
+ */
 class Segment extends UIComponent<Extendable<SegmentProps>, any> {
   static className = 'ui-segment'
 

test/specs/commonTests/isConformant.tsx

@@ -104,6 +104,27 @@ export default (Component, options: Conformant = {}) => {
     return null
   }
 
+  // ----------------------------------------
+  // Docblock description
+  // ----------------------------------------
+  const hasDocblockDescription = info.docblock.description.join('').trim().length > 0
+
+  test('has a docblock description', () => {
+    expect(hasDocblockDescription).toEqual(true)
+  })
+
+  if (hasDocblockDescription) {
+    const minWords = 5
+    const maxWords = 25
+    test(`docblock description is long enough to be meaningful (>${minWords} words)`, () => {
+      expect(_.words(info.docblock.description).length).toBeGreaterThan(minWords)
+    })
+
+    test(`docblock description is short enough to be quickly understood (<${maxWords} words)`, () => {
+      expect(_.words(info.docblock.description).length).toBeLessThan(maxWords)
+    })
+  }
+
   // ----------------------------------------
   // Class and file name
   // ----------------------------------------
@@ -303,7 +324,7 @@ export default (Component, options: Conformant = {}) => {
               'forgot to use `getUnhandledProps` util to spread the `rest` props.',
           )
         }
-        const customHandler = eventTarget.prop([listenerName])
+        const customHandler = eventTarget.prop(listenerName)
 
         if (customHandler) {
           customHandler(eventShape)

test/specs/components/RadioGroup/RadioGroup-test.tsx

@@ -42,9 +42,7 @@ const getShorthandItems = (props?: { disabledItem?: number }) => [
 ]
 
 describe('RadioGroup', () => {
-  describe('isConformant', () => {
-    isConformant(RadioGroup)
-  })
+  isConformant(RadioGroup)
 
   describe('accessibility', () => {
     handlesAccessibility(RadioGroup, {

test/specs/components/RadioGroup/RadioGroupItem-test.ts

@@ -3,9 +3,7 @@ import { isConformant, handlesAccessibility } from 'test/specs/commonTests'
 import RadioGroupItem from 'src/components/RadioGroup/RadioGroupItem'
 
 describe('RadioGroupItem', () => {
-  describe('isConformant', () => {
-    isConformant(RadioGroupItem)
-  })
+  isConformant(RadioGroupItem)
 
   describe('accessibility', () => {
     handlesAccessibility(RadioGroupItem, {