This document describes the test suites for CLI commands in the shadcn package. It covers test patterns for init, add, and registry commands, including authentication scenarios, multi-registry testing, and fixture management. These tests ensure that the CLI correctly interacts with the registry system, transforms source code, and updates project configurations like components.json and globals.css.
The CLI command tests are organized into several primary test files within the packages/tests and packages/shadcn directories. The repository uses vitest as the test runner, configured with extended timeouts to accommodate I/O-heavy CLI operations.
| Test File | Primary Focus | Key Test Categories |
|---|---|---|
init.test.ts | Project initialization | Default config, style extensions, custom aliases, and framework-specific setups packages/tests/src/tests/init.test.ts13-118 |
add.test.ts | Component installation | Single/multiple items, dependencies, and path handling packages/shadcn/src/commands/add.test.ts242-270 |
registries.test.ts | Multi-registry system | Namespaced components, authentication (Bearer/API Key), and cross-registry dependencies packages/tests/src/tests/registries.test.ts13-270 |
update-files.test.ts | File System Operations | Path resolution, target alias mapping, and framework-specific file placement packages/shadcn/src/utils/updaters/update-files.test.ts61-258 |
utils.test.ts (MCP) | AI Assistant Output | Formatting search results and add commands for MCP clients packages/shadcn/src/mcp/utils.test.ts34-130 |
Sources: packages/tests/src/tests/init.test.ts13-118 packages/shadcn/src/commands/add.test.ts242-270 packages/tests/src/tests/registries.test.ts13-270 packages/shadcn/src/utils/updaters/update-files.test.ts61-258 packages/shadcn/src/mcp/utils.test.ts34-130
The following diagram illustrates the lifecycle of a typical CLI command test, from fixture creation to final assertion.
Sources: packages/tests/src/utils/helpers.ts18-28 packages/tests/src/utils/helpers.ts69-96 packages/tests/src/utils/registry.ts5-14 packages/tests/src/utils/setup.ts5-48
init Command TestingThe init command tests validate project initialization across different frameworks. Tests use the createFixtureTestDirectory() helper to create isolated environments from fixtures like next-app or vite-app packages/tests/src/tests/init.test.ts15
The primary test for next-app validates the creation of a standard components.json and the installation of base utilities packages/tests/src/tests/init.test.ts14-53
Expected components.json Structure:
packages/tests/src/tests/init.test.ts22-39
style: "base-nova"tailwind.css: "app/globals.css"tailwind.baseColor: "neutral"aliases: Maps components, utils, ui, lib, and hooks to @/* paths.The suite tests the ability to initialize using a custom registry URL. This validates that the CLI can fetch remote styles and merge CSS variables correctly packages/tests/src/tests/init.test.ts122-212
CSS Variable Validation:
Tests use cssHasProperties() to ensure the globals.css contains required layers and variables:
@layer base packages/tests/src/tests/init.test.ts47:root and .dark blocks packages/tests/src/tests/init.test.ts48-49--background and --foreground packages/tests/src/tests/init.test.ts51-52Sources: packages/tests/src/tests/init.test.ts13-212 packages/tests/src/utils/helpers.ts98-115
add Command TestingThe add command is tested against several scenarios to ensure robust component delivery. Tests verify that the command delegates to addComponents correctly when a valid project exists packages/shadcn/src/commands/add.test.ts256-269
| Scenario | Test Logic |
|---|---|
| Happy Path | Validates that add button calls addComponents with correct arguments packages/shadcn/src/commands/add.test.ts256-269 |
| Recursive Deps | Ensures alert-dialog also installs button via registryDependencies packages/tests/src/utils/registry.ts127-152 |
| Vite App Aliases | Verifies custom aliases (e.g., #custom/components) are correctly applied in component imports packages/tests/src/tests/init.test.ts80-119 |
The CLI supports writing files to specific targets. Tests in update-files.test.ts verify that aliases like @ui or @lib resolve correctly to the paths defined in components.json packages/shadcn/src/utils/updaters/update-files.test.ts117-160
resolveFilePath handles @components, @ui, @lib, and @hooks packages/shadcn/src/utils/updaters/update-files.test.ts117-137~ as a project root indicator packages/shadcn/src/utils/updaters/update-files.test.ts88-97#components packages/shadcn/src/utils/updaters/update-files.test.ts162-190Sources: packages/shadcn/src/commands/add.test.ts242-270 packages/shadcn/src/utils/updaters/update-files.test.ts61-258 packages/tests/src/tests/init.test.ts80-119
The registries.test.ts suite focuses on private registry scenarios. The createRegistryServer mock supports several authentication methods by validating incoming headers packages/tests/src/utils/registry.ts157-234
Authorization: Bearer header packages/tests/src/utils/registry.ts158-166x-api-key header packages/tests/src/utils/registry.ts203-211x-client-secret and x-client-id packages/tests/src/utils/registry.ts213-225The CLI looks up registries in components.json and applies headers to requests.
Sources: packages/tests/src/tests/registries.test.ts13-270 packages/tests/src/utils/registry.ts157-234
The Model Context Protocol (MCP) integration requires specific formatting for AI assistants. Tests in mcp/utils.test.ts ensure the CLI provides clear, actionable output.
| Utility | Test Logic |
|---|---|
formatSearchResultsWithPagination | Verifies headers include query/registry info and pagination hints packages/shadcn/src/mcp/utils.test.ts34-108 |
findUnknownTypesMessage | Ensures helpful error messages when searching for invalid registry types packages/shadcn/src/mcp/utils.test.ts132-158 |
formatSkippedRegistries | Validates reporting of registries that failed to load during search packages/shadcn/src/mcp/utils.test.ts160-188 |
Sources: packages/shadcn/src/mcp/utils.test.ts34-190
npxShadcnA wrapper around execa that runs the local build of the CLI (packages/shadcn/dist/index.js). It automatically injects the REGISTRY_URL and SHADCN_TEMPLATE_DIR environment variables to point to local test resources packages/tests/src/utils/helpers.ts69-96
createRegistryServerA dynamic HTTP server used in tests to mock the component registry. It handles:
registries.json: Returns an empty array to test manual configuration packages/tests/src/utils/registry.ts19-24icons/index: Mocks icon mappings for Lucide and Radix packages/tests/src/utils/registry.ts29-44colors/neutral: Serves Tailwind v3 and v4 CSS variable templates packages/tests/src/utils/registry.ts46-87cssHasPropertiesA utility that verifies CSS content using regular expressions to ensure specific selectors contain the expected property-value pairs after transformation packages/tests/src/utils/helpers.ts98-115
Sources: packages/tests/src/utils/helpers.ts69-115 packages/tests/src/utils/registry.ts5-153
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.