primer · francinelucca · Dec 18, 2025 · Nov 22, 2025 · Nov 25, 2025 · Nov 25, 2025
@@ -50,6 +50,8 @@ jobs:
         run: npm run lint:md
       - name: Lint npm packages
         run: npx turbo lint:npm
+      - name: Check className test coverage
+        run: npm run test:classname-coverage
 
   test:
     runs-on: ubuntu-latest

@@ -30,6 +30,7 @@
     "test": "vitest",
     "test:type-check": "tsc --noEmit",
     "test:update": "npm run test -- -u",
+    "test:classname-coverage": "node script/check-classname-tests.mjs",
     "type-check": "tsc --noEmit && turbo type-check",
     "release": "npm run build && changeset publish",
     "reset": "script/reset",

@@ -4,8 +4,11 @@ import userEvent from '@testing-library/user-event'
 import ActionBar from './'
 import {BoldIcon, ItalicIcon, CodeIcon} from '@primer/octicons-react'
 import {useState} from 'react'
+import {implementsClassName} from '../utils/testing'
+import classes from './ActionBar.module.css'
 
 describe('ActionBar', () => {
+  implementsClassName(ActionBar, classes.Nav)
   afterEach(() => {
     vi.clearAllMocks()
   })

@@ -2,8 +2,15 @@ import {describe, it, expect, vi} from 'vitest'
 import {render as HTMLRender} from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
 import {ActionList} from '.'
+import {implementsClassName} from '../utils/testing'
+import classes from './ActionList.module.css'
 
 describe('ActionList', () => {
+  implementsClassName(ActionList, classes.ActionList)
+  implementsClassName(ActionList.LeadingVisual, classes.LeadingVisual)
+  implementsClassName(ActionList.TrailingVisual, classes.TrailingVisual)
+  implementsClassName(ActionList.TrailingAction, classes.TrailingAction)
+  implementsClassName(ActionList.Divider, classes.Divider)
   it('should warn when selected is provided without a selectionVariant on parent', async () => {
     // we expect console.warn to be called, so we spy on that in the test
     const spy = vi.spyOn(console, 'warn').mockImplementation(() => vi.fn())
@@ -59,17 +66,6 @@ describe('ActionList', () => {
     expect(document.activeElement).toHaveTextContent('Option 4')
   })
 
-  it('should support a custom `className` on the outermost element', () => {
-    const Element = () => {
-      return (
-        <ActionList className="test-class-name">
-          <ActionList.Item>Item</ActionList.Item>
-        </ActionList>
-      )
-    }
-    expect(HTMLRender(<Element />).container.querySelector('ul')).toHaveClass('test-class-name')
-  })
-
   it('divider should support a custom `className`', () => {
     const Element = () => {
       return (

@@ -1,8 +1,11 @@
 import {expect, it, describe} from 'vitest'
 import {render as HTMLRender} from '@testing-library/react'
 import {ActionList} from '.'
+import {implementsClassName} from '../utils/testing'
+import classes from './ActionList.module.css'
 
 describe('ActionList.Description', () => {
+  implementsClassName(ActionList.Description, classes.Description)
   it('should render the description as inline without truncation by default', () => {
     const {getByText} = HTMLRender(
       <ActionList>

@@ -3,8 +3,22 @@ import {render as HTMLRender} from '@testing-library/react'
 import BaseStyles from '../BaseStyles'
 import {ActionList} from '.'
 import {ActionMenu} from '..'
+import {implementsClassName} from '../utils/testing'
+import classes from './Group.module.css'
 
 describe('ActionList.Group', () => {
+  implementsClassName(
+    props => (
+      <ActionList>
+        <ActionList.Group {...props}>
+          <ActionList.Item>item</ActionList.Item>
+        </ActionList.Group>
+      </ActionList>
+    ),
+    classes.Group,
+  )
+  implementsClassName(ActionList.GroupHeading, classes.GroupHeading)
+
   it('should throw an error when ActionList.GroupHeading has an `as` prop when it is used within ActionMenu context', async () => {
     expect(() =>
       HTMLRender(
@@ -122,19 +136,4 @@ describe('ActionList.Group', () => {
     const list = container.querySelector(`li[data-test-id='ActionList.Group'] > ul`)
     expect(list).toHaveAttribute('aria-label', 'Animals')
   })
-
-  it('should support a custom `className` on the outermost element', () => {
-    const Element = () => {
-      return (
-        <ActionList>
-          <ActionList.Group>
-            <ActionList.GroupHeading as="h2" className="test-class-name">
-              Test
-            </ActionList.GroupHeading>
-          </ActionList.Group>
-        </ActionList>
-      )
-    }
-    expect(HTMLRender(<Element />).container.querySelector('h2')).toHaveClass('test-class-name')
-  })
 })
@@ -3,8 +3,21 @@ import {render as HTMLRender} from '@testing-library/react'
 import BaseStyles from '../BaseStyles'
 import {ActionList} from '.'
 import {ActionMenu} from '..'
+import {implementsClassName} from '../utils/testing'
+import classes from './Heading.module.css'
 
 describe('ActionList.Heading', () => {
+  implementsClassName(
+    props => (
+      <ActionList>
+        <ActionList.Heading as="h1" {...props}>
+          Heading
+        </ActionList.Heading>
+      </ActionList>
+    ),
+    classes.ActionListHeader,
+  )
+
   it('should render the ActionList.Heading component as a heading with the given heading level', async () => {
     const container = HTMLRender(
       <ActionList>
@@ -47,15 +60,4 @@ describe('ActionList.Heading', () => {
       "ActionList.Heading shouldn't be used within an ActionMenu container. Menus are labelled by the menu button's name.",
     )
   })
-
-  it('should support a custom `className` on the outermost element', () => {
-    const actionList = HTMLRender(
-      <ActionList>
-        <ActionList.Heading as="h2" className="test-class-name">
-          Filter by
-        </ActionList.Heading>
-      </ActionList>,
-    )
-    expect(actionList.container.querySelector('h2')).toHaveClass('test-class-name')
-  })
 })
@@ -4,6 +4,8 @@ import userEvent from '@testing-library/user-event'
 import React, {type JSX} from 'react'
 import {ActionList} from '.'
 import {BookIcon} from '@primer/octicons-react'
+import {implementsClassName} from '../utils/testing'
+import classes from './ActionList.module.css'
 
 function SimpleActionList(): JSX.Element {
   return (
@@ -60,6 +62,8 @@ function SingleSelectListStory(): JSX.Element {
 }
 
 describe('ActionList.Item', () => {
+  implementsClassName(ActionList.Item, classes.ActionListItem)
+  implementsClassName(ActionList.LinkItem)
   it('should have aria-keyshortcuts applied to the correct element', async () => {
     const {container} = HTMLRender(<SimpleActionList />)
     const linkOptions = await waitFor(() => container.querySelectorAll('a'))

@@ -11,6 +11,7 @@ import {MixedSelection} from '../ActionMenu/ActionMenu.examples.stories'
 import {SearchIcon, KebabHorizontalIcon} from '@primer/octicons-react'
 
 import type {JSX} from 'react'
+import {implementsClassName} from '../utils/testing'
 
 function Example(): JSX.Element {
   return (
@@ -120,6 +121,8 @@ function ExampleWithSubmenus(): JSX.Element {
 }
 
 describe('ActionMenu', () => {
+  implementsClassName(ActionMenu.Button)
+
   it('should open Menu on MenuButton click', async () => {
     const component = HTMLRender(<Example />)
     const button = component.getByRole('button')

@@ -6,18 +6,24 @@ import {AnchoredOverlay} from '../AnchoredOverlay'
 import {Button} from '../Button'
 import BaseStyles from '../BaseStyles'
 import type {AnchorPosition} from '@primer/behaviors'
+import {implementsClassName} from '../utils/testing'
+
+import overlayClasses from '../Overlay/Overlay.module.css'
+
 type TestComponentSettings = {
   initiallyOpen?: boolean
   onOpenCallback?: (gesture: string) => void
   onCloseCallback?: (gesture: string) => void
   onPositionChange?: ({position}: {position: AnchorPosition}) => void
+  className?: string
 }
 
 const AnchoredOverlayTestComponent = ({
   initiallyOpen = false,
   onOpenCallback,
   onCloseCallback,
   onPositionChange,
+  className,
 }: TestComponentSettings = {}) => {
   const [open, setOpen] = useState(initiallyOpen)
   const onOpen = useCallback(
@@ -42,6 +48,7 @@ const AnchoredOverlayTestComponent = ({
         onClose={onClose}
         renderAnchor={props => <Button {...props}>Anchor Button</Button>}
         onPositionChange={onPositionChange}
+        className={className}
       >
         <button type="button">Focusable Child</button>
       </AnchoredOverlay>
@@ -50,6 +57,7 @@ const AnchoredOverlayTestComponent = ({
 }
 
 describe('AnchoredOverlay', () => {
+  implementsClassName(props => <AnchoredOverlayTestComponent initiallyOpen={true} {...props} />, overlayClasses.Overlay)
   it('should call onOpen when the anchor is clicked', async () => {
     const mockOpenCallback = vi.fn()
     const mockCloseCallback = vi.fn()

@@ -6,6 +6,8 @@ import type {AutocompleteInputProps} from '../Autocomplete'
 import Autocomplete from '../Autocomplete'
 import type {AutocompleteMenuInternalProps, AutocompleteMenuItem} from '../Autocomplete/AutocompleteMenu'
 import BaseStyles from '../BaseStyles'
+import {implementsClassName} from '../utils/testing'
+import classes from './AutocompleteOverlay.module.css'
 
 const mockItems = [
   {text: 'zero', id: '0'},
@@ -47,6 +49,11 @@ const LabelledAutocomplete = <T extends AutocompleteMenuItem>({
 
 describe('Autocomplete', () => {
   describe('Autocomplete.Input', () => {
+    implementsClassName(props => (
+      <Autocomplete>
+        <Autocomplete.Input {...props} />
+      </Autocomplete>
+    ))
     it('calls onChange', async () => {
       const user = userEvent.setup()
       const onChangeMock = vi.fn()
@@ -214,15 +221,6 @@ describe('Autocomplete', () => {
 
       expect(getByDisplayValue('0')).toBeDefined()
     })
-
-    it('should support `className` on the outermost element', () => {
-      const Element = () => (
-        <Autocomplete>
-          <Autocomplete.Input className={'test-class-name'} />
-        </Autocomplete>
-      )
-      expect(render(<Element />).container.firstChild).toHaveClass('test-class-name')
-    })
   })
 
   describe('Autocomplete.Menu', () => {
@@ -444,23 +442,20 @@ describe('Autocomplete', () => {
     })
   })
 
-  describe('Autocomplete.Overlay', () => {
-    it('should support `className` on the outermost element', async () => {
-      const Element = ({className}: {className: string}) => (
+  // TODO: Enable once className override bug is fixed in Autocomplete.Overlay, also remember to remove from ignore list on script/check-classname-tests.mjs
+  // eslint-disable-next-line vitest/no-disabled-tests
+  describe.skip('Autocomplete.Overlay', () => {
+    implementsClassName(
+      props => (
         <Autocomplete id="autocompleteId">
           <Autocomplete.Input />
-          <Autocomplete.Overlay className={className} visibility="visible">
+          <Autocomplete.Overlay {...props} visibility="visible">
             hi
           </Autocomplete.Overlay>
         </Autocomplete>
-      )
-      const {container: elementContainer, getByRole} = render(<Element className="test-class-name" />)
-      const inputNode = getByRole('combobox')
-      await userEvent.click(inputNode)
-      await userEvent.keyboard('{ArrowDown}')
-      // overlay is a sibling of elementContainer
-      expect(elementContainer.parentElement?.querySelectorAll('.test-class-name')).toHaveLength(1)
-    })
+      ),
+      classes.Overlay,
+    )
   })
 
   describe('null context', () => {

@@ -1,12 +1,11 @@
 import {describe, expect, it} from 'vitest'
 import {render, screen} from '@testing-library/react'
 import Avatar from '../Avatar'
+import {implementsClassName} from '../utils/testing'
+import classes from './Avatar.module.css'
 
 describe('Avatar', () => {
-  it('should support `className` on the outermost element', () => {
-    const Element = () => <Avatar src="primer.png" className={'test-class-name'} />
-    expect(render(<Element />).container.firstChild).toHaveClass('test-class-name')
-  })
+  implementsClassName(Avatar, classes.Avatar)
 
   it('renders small by default', () => {
     const size = 20

@@ -1,6 +1,8 @@
 import {describe, expect, it} from 'vitest'
 import {render} from '@testing-library/react'
 import {AvatarStack} from '..'
+import {implementsClassName} from '../utils/testing'
+import classes from './AvatarStack.module.css'
 
 const avatarComp = (
   <AvatarStack>
@@ -21,17 +23,7 @@ const rightAvatarComp = (
 )
 
 describe('AvatarStack', () => {
-  it('should support `className` on the outermost element', () => {
-    const Element = () => (
-      <AvatarStack className={'test-class-name'}>
-        <img src="https://avatars.githubusercontent.com/primer" alt="" />
-        <img src="https://avatars.githubusercontent.com/github" alt="" />
-        <img src="https://avatars.githubusercontent.com/primer" alt="" />
-        <img src="https://avatars.githubusercontent.com/github" alt="" />
-      </AvatarStack>
-    )
-    expect(render(<Element />).container.firstChild).toHaveClass('test-class-name')
-  })
+  implementsClassName(AvatarStack, classes.AvatarStack)
 
   it('respects alignRight props', () => {
     const {container} = render(rightAvatarComp)

@@ -2,19 +2,18 @@ import {describe, expect, it, vi} from 'vitest'
 import {render, screen} from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
 import {Banner} from '../Banner'
+import {implementsClassName} from '../utils/testing'
+import classes from './Banner.module.css'
 
 describe('Banner', () => {
+  implementsClassName(props => <Banner title="test" {...props} />, classes.Banner)
+
   it('should render as a region element', () => {
     render(<Banner title="test" />)
     expect(screen.getByRole('region', {name: 'Information'})).toBeInTheDocument()
     expect(screen.getByRole('heading', {name: 'test'})).toBeInTheDocument()
   })
 
-  it('should support a custom `className` on the outermost element', () => {
-    const Element = () => <Banner title="test" className="test-class-name" />
-    expect(render(<Element />).container.firstChild).toHaveClass('test-class-name')
-  })
-
   it('should label the landmark element with the corresponding variant label text', () => {
     render(<Banner title="test" />)
     expect(screen.getByRole('region')).toEqual(screen.getByLabelText('Information'))

@@ -2,12 +2,11 @@ import {describe, expect, it, vi} from 'vitest'
 import {render, screen} from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
 import {Blankslate} from '../Blankslate'
+import {implementsClassName} from '../utils/testing'
+import classes from './Blankslate.module.css'
 
 describe('Blankslate', () => {
-  it('should support a custom `className` on the outermost, non-container element', () => {
-    const {container} = render(<Blankslate className="test">Test content</Blankslate>)
-    expect(container.firstChild!.firstChild).toHaveClass('test')
-  })
+  implementsClassName(Blankslate, classes.Blankslate)
 
   it('should render with border when border is true', () => {
     const {container} = render(<Blankslate border>Test content</Blankslate>)