@kubb/plugin-cypress 5.0.0-beta.4 → 5.0.0-beta.42

package/package.json

@@ -1,21 +1,15 @@
 {
   "name": "@kubb/plugin-cypress",
-  "version": "5.0.0-beta.4",
-  "description": "Cypress test generator plugin for Kubb, creating end-to-end tests from OpenAPI specifications for automated API testing.",
+  "version": "5.0.0-beta.42",
+  "description": "Generate Cypress request commands and e2e test fixtures from your OpenAPI specification, enabling automated API testing with zero manual setup.",
   "keywords": [
-    "api-testing",
-    "code-generator",
+    "code-generation",
     "codegen",
     "cypress",
     "e2e-testing",
-    "end-to-end",
-    "integration-testing",
     "kubb",
-    "oas",
     "openapi",
-    "plugins",
     "swagger",
-    "test-automation",
     "test-generation",
     "testing",
     "typescript"
@@ -53,15 +47,16 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/core": "5.0.0-beta.4",
-    "@kubb/renderer-jsx": "5.0.0-beta.4",
-    "@kubb/plugin-ts": "5.0.0-beta.4"
+    "@kubb/core": "5.0.0-beta.42",
+    "@kubb/renderer-jsx": "5.0.0-beta.42",
+    "@kubb/plugin-ts": "5.0.0-beta.42"
   },
   "devDependencies": {
+    "@internals/shared": "0.0.0",
     "@internals/utils": "0.0.0"
   },
   "peerDependencies": {
-    "@kubb/renderer-jsx": "5.0.0-beta.4"
+    "@kubb/renderer-jsx": "5.0.0-beta.42"
   },
   "size-limit": [
     {
@@ -80,6 +75,7 @@
     "lint:fix": "oxlint --fix .",
     "release": "pnpm publish --no-git-check",
     "release:canary": "bash ../../.github/canary.sh && node ../../scripts/build.js canary && pnpm publish --no-git-check",
+    "release:stage": "pnpm stage publish --no-git-check",
     "start": "tsdown --watch",
     "test": "vitest --passWithNoTests",
     "typecheck": "tsc -p ./tsconfig.json --noEmit --emitDeclarationOnly false"

package/src/components/Request.tsx

@@ -1,3 +1,4 @@
+import { getOperationParameters } from '@internals/shared'
 import { camelCase, URLPath } from '@internals/utils'
 import { ast } from '@kubb/core'
 import type { ResolverTs } from '@kubb/plugin-ts'
@@ -19,7 +20,7 @@ type Props = {
    * TypeScript resolver for resolving param/data/response type names
    */
   resolver: ResolverTs
-  baseURL: string | undefined
+  baseURL: string | null | undefined
   dataReturnType: PluginCypress['resolvedOptions']['dataReturnType']
   paramsCasing: PluginCypress['resolvedOptions']['paramsCasing']
   paramsType: PluginCypress['resolvedOptions']['paramsType']
@@ -29,6 +30,7 @@ type Props = {
 const declarationPrinter = functionPrinter({ mode: 'declaration' })
 
 export function Request({ baseURL = '', name, dataReturnType, resolver, node, paramsType, pathParamsType, paramsCasing }: Props): KubbReactNode {
+  if (!ast.isHttpOperationNode(node)) return null
   const paramsNode = ast.createOperationParams(node, {
     paramsType,
     pathParamsType,
@@ -47,10 +49,7 @@ export function Request({ baseURL = '', name, dataReturnType, resolver, node, pa
   const responseType = resolver.resolveResponseName(node)
   const returnType = dataReturnType === 'data' ? `Cypress.Chainable<${responseType}>` : `Cypress.Chainable<Cypress.Response<${responseType}>>`
 
-  const casedPathParams = ast.caseParams(
-    node.parameters.filter((p) => p.in === 'path'),
-    paramsCasing,
-  )
+  const casedPathParams = getOperationParameters(node, { paramsCasing }).path
   // Build a lookup keyed by camelCase-normalized name so that path-template names
   // (e.g. `{pet_id}`) correctly resolve to the function-parameter name (`petId`)
   // even when the OpenAPI spec has inconsistent casing between the two.
@@ -62,11 +61,11 @@ export function Request({ baseURL = '', name, dataReturnType, resolver, node, pa
     replacer: (param) => pathParamNameMap.get(camelCase(param)) ?? param,
   })
 
-  const requestOptions: string[] = [`method: '${node.method}'`, `url: ${urlTemplate}`]
+  const requestOptions: Array<string> = [`method: '${node.method}'`, `url: ${urlTemplate}`]
 
-  const queryParams = node.parameters.filter((p) => p.in === 'query')
+  const queryParams = getOperationParameters(node).query
   if (queryParams.length > 0) {
-    const casedQueryParams = ast.caseParams(queryParams, paramsCasing)
+    const casedQueryParams = getOperationParameters(node, { paramsCasing }).query
     // When paramsCasing renames query params (e.g. page_size → pageSize), we must remap
     // the camelCase keys back to the original API names before passing them to `qs`.
     const needsQsTransform = casedQueryParams.some((p, i) => p.name !== queryParams[i]!.name)
@@ -78,9 +77,9 @@ export function Request({ baseURL = '', name, dataReturnType, resolver, node, pa
     }
   }
 
-  const headerParams = node.parameters.filter((p) => p.in === 'header')
+  const headerParams = getOperationParameters(node).header
   if (headerParams.length > 0) {
-    const casedHeaderParams = ast.caseParams(headerParams, paramsCasing)
+    const casedHeaderParams = getOperationParameters(node, { paramsCasing }).header
     // When paramsCasing renames header params (e.g. x-api-key → xApiKey), we must remap
     // the camelCase keys back to the original API names before passing them to `headers`.
     const needsHeaderTransform = casedHeaderParams.some((p, i) => p.name !== headerParams[i]!.name)

package/src/generators/cypressGenerator.tsx

@@ -1,14 +1,21 @@
+import { resolveOperationTypeNames } from '@internals/shared'
 import { ast, defineGenerator } from '@kubb/core'
 import { pluginTsName } from '@kubb/plugin-ts'
-import { File, jsxRenderer } from '@kubb/renderer-jsx'
+import { File, jsxRendererSync } from '@kubb/renderer-jsx'
 import { Request } from '../components/Request.tsx'
 import type { PluginCypress } from '../types.ts'
 
+/**
+ * Built-in generator for `@kubb/plugin-cypress`. Emits one typed
+ * `cy.request()` wrapper per OpenAPI operation, ready to call inside Cypress
+ * test specs and custom commands.
+ */
 export const cypressGenerator = defineGenerator<PluginCypress>({
   name: 'cypress',
-  renderer: jsxRenderer,
+  renderer: jsxRendererSync,
   operation(node, ctx) {
-    const { adapter, config, resolver, driver, root } = ctx
+    if (!ast.isHttpOperationNode(node)) return null
+    const { config, resolver, driver, root } = ctx
     const { output, baseURL, dataReturnType, paramsCasing, paramsType, pathParamsType, group } = ctx.options
 
     const pluginTs = driver.getPlugin(pluginTsName)
@@ -19,29 +26,20 @@ export const cypressGenerator = defineGenerator<PluginCypress>({
 
     const tsResolver = driver.getResolver(pluginTsName)
 
-    const casedParams = ast.caseParams(node.parameters, paramsCasing)
-
-    const pathParams = casedParams.filter((p) => p.in === 'path')
-    const queryParams = casedParams.filter((p) => p.in === 'query')
-    const headerParams = casedParams.filter((p) => p.in === 'header')
-
-    const importedTypeNames = [
-      ...pathParams.map((p) => tsResolver.resolvePathParamsName(node, p)),
-      ...queryParams.map((p) => tsResolver.resolveQueryParamsName(node, p)),
-      ...headerParams.map((p) => tsResolver.resolveHeaderParamsName(node, p)),
-      node.requestBody?.content?.[0]?.schema ? tsResolver.resolveDataName(node) : undefined,
-      tsResolver.resolveResponseName(node),
-    ].filter(Boolean)
+    const importedTypeNames = resolveOperationTypeNames(node, tsResolver, { paramsCasing })
 
     const meta = {
       name: resolver.resolveName(node.operationId),
-      file: resolver.resolveFile({ name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path }, { root, output, group }),
+      file: resolver.resolveFile(
+        { name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
+        { root, output, group: group ?? undefined },
+      ),
       fileTs: tsResolver.resolveFile(
         { name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
         {
           root,
           output: pluginTs.options?.output ?? output,
-          group: pluginTs.options?.group,
+          group: pluginTs.options?.group ?? undefined,
         },
       ),
     } as const
@@ -51,12 +49,10 @@ export const cypressGenerator = defineGenerator<PluginCypress>({
         baseName={meta.file.baseName}
         path={meta.file.path}
         meta={meta.file.meta}
-        banner={resolver.resolveBanner(adapter.inputNode, { output, config })}
-        footer={resolver.resolveFooter(adapter.inputNode, { output, config })}
+        banner={resolver.resolveBanner(ctx.meta, { output, config, file: { path: meta.file.path, baseName: meta.file.baseName } })}
+        footer={resolver.resolveFooter(ctx.meta, { output, config, file: { path: meta.file.path, baseName: meta.file.baseName } })}
       >
-        {meta.fileTs && importedTypeNames.length > 0 && (
-          <File.Import name={Array.from(new Set(importedTypeNames))} root={meta.file.path} path={meta.fileTs.path} isTypeOnly />
-        )}
+        {meta.fileTs && importedTypeNames.length > 0 && <File.Import name={importedTypeNames} root={meta.file.path} path={meta.fileTs.path} isTypeOnly />}
         <Request
           name={meta.name}
           node={node}

package/src/plugin.ts

@@ -1,29 +1,36 @@
-import { camelCase } from '@internals/utils'
-import { definePlugin, type Group } from '@kubb/core'
+import { createGroupConfig } from '@internals/shared'
+import { definePlugin } from '@kubb/core'
 import { pluginTsName } from '@kubb/plugin-ts'
 import { cypressGenerator } from './generators/cypressGenerator.tsx'
 import { resolverCypress } from './resolvers/resolverCypress.ts'
 import type { PluginCypress } from './types.ts'
 
 /**
- * Canonical plugin name for `@kubb/plugin-cypress`, used to identify the plugin
- * in driver lookups and warnings.
+ * Canonical plugin name for `@kubb/plugin-cypress`. Used for driver lookups and
+ * cross-plugin dependency references.
  */
 export const pluginCypressName = 'plugin-cypress' satisfies PluginCypress['name']
 
 /**
- * The `@kubb/plugin-cypress` plugin factory.
- *
- * Generates Cypress `cy.request()` test functions from an OpenAPI/AST `RootNode`.
- * Walks operations, delegates rendering to the active generators,
- * and writes barrel files based on `output.barrelType`.
+ * Generates one typed `cy.request()` wrapper per OpenAPI operation. Each helper
+ * has typed path params, body, query, and a typed response, so failing API
+ * calls in Cypress show up at compile time instead of inside the test runner.
  *
  * @example
  * ```ts
- * import pluginCypress from '@kubb/plugin-cypress'
+ * import { defineConfig } from 'kubb'
+ * import { pluginTs } from '@kubb/plugin-ts'
+ * import { pluginCypress } from '@kubb/plugin-cypress'
  *
  * export default defineConfig({
- *   plugins: [pluginCypress({ output: { path: 'cypress' } })],
+ *   input: { path: './petStore.yaml' },
+ *   output: { path: './src/gen' },
+ *   plugins: [
+ *     pluginTs(),
+ *     pluginCypress({
+ *       output: { path: './cypress' },
+ *     }),
+ *   ],
  * })
  * ```
  */
@@ -44,19 +51,7 @@ export const pluginCypress = definePlugin<PluginCypress>((options) => {
     generators: userGenerators = [],
   } = options
 
-  const groupConfig = group
-    ? ({
-        ...group,
-        name: group.name
-          ? group.name
-          : (ctx: { group: string }) => {
-              if (group.type === 'path') {
-                return `${ctx.group.split('/')[1]}`
-              }
-              return `${camelCase(ctx.group)}Requests`
-            },
-      } satisfies Group)
-    : undefined
+  const groupConfig = createGroupConfig(group, { suffix: 'Requests' })
 
   return {
     name: pluginCypressName,

package/src/resolvers/resolverCypress.ts

@@ -3,20 +3,27 @@ import { defineResolver } from '@kubb/core'
 import type { PluginCypress } from '../types.ts'
 
 /**
- * Naming convention resolver for Cypress plugin.
+ * Default resolver used by `@kubb/plugin-cypress`. Decides the names and file
+ * paths for every generated `cy.request()` wrapper. Functions and files use
+ * camelCase, matching the convention from `@kubb/plugin-client`.
  *
- * Provides default naming helpers using camelCase for functions and file paths.
+ * @example Resolve a helper name
+ * ```ts
+ * import { resolverCypress } from '@kubb/plugin-cypress'
  *
- * @example
- * `resolverCypress.default('list pets', 'function')  // → 'listPets'`
+ * resolverCypress.default('list pets', 'function') // 'listPets'
+ * ```
  */
-export const resolverCypress = defineResolver<PluginCypress>((ctx) => ({
+export const resolverCypress = defineResolver<PluginCypress>(() => ({
   name: 'default',
   pluginName: 'plugin-cypress',
   default(name, type) {
     return camelCase(name, { isFile: type === 'file' })
   },
   resolveName(name) {
-    return ctx.default(name, 'function')
+    return this.default(name, 'function')
+  },
+  resolvePathName(name, type) {
+    return this.default(name, type)
   },
 }))

package/src/types.ts

@@ -11,6 +11,10 @@ export type ResolverCypress = Resolver & {
    * `resolver.resolveName('show pet by id') // -> 'showPetById'`
    */
   resolveName(this: ResolverCypress, name: string): string
+  /**
+   * Resolves the output file name for a Cypress request module.
+   */
+  resolvePathName(this: ResolverCypress, name: string, type?: 'file' | 'function' | 'type' | 'const'): string
 }
 
 /**
@@ -19,21 +23,23 @@ export type ResolverCypress = Resolver & {
 type ParamsTypeOptions =
   | {
       /**
-       * All parameters merged into a single destructured object.
+       * Every operation parameter is wrapped in a single destructured object argument.
        */
       paramsType: 'object'
       /**
-       * Not applicable when all parameters are merged into a single object.
+       * `pathParamsType` has no effect when `paramsType` is `'object'`.
        */
       pathParamsType?: never
     }
   | {
       /**
-       * Each parameter group emitted as a separate function argument.
+       * Each parameter group is emitted as a separate positional function argument.
        */
       paramsType?: 'inline'
       /**
-       * How path parameters are arranged: grouped in an object or spread inline.
+       * How URL path parameters are arranged inside the inline argument list.
+       * - `'object'` groups them into one destructured object.
+       * - `'inline'` emits each path param as its own argument.
        *
        * @default 'inline'
        */
@@ -42,50 +48,56 @@ type ParamsTypeOptions =
 
 export type Options = {
   /**
-   * Specify the export location for the files and define the behavior of the output.
-   * @default { path: 'cypress', barrelType: 'named' }
+   * Where the generated Cypress helpers are written and how they are exported.
+   *
+   * @default { path: 'cypress', barrel: { type: 'named' } }
    */
   output?: Output
   /**
-   * Return type when calling cy.request: response data only or full response.
+   * Shape of the value returned from each helper.
+   * - `'data'` — only the response body.
+   * - `'full'` — the full Cypress response object (headers, status, body).
    *
    * @default 'data'
    */
   dataReturnType?: 'data' | 'full'
   /**
-   * Apply casing to parameter names.
+   * Rename parameter properties in the generated helpers (path, query, headers).
+   *
+   * @note Must match the value of `paramsCasing` on `@kubb/plugin-ts`.
    */
   paramsCasing?: 'camelcase'
   /**
-   * Base URL prepended to every generated request URL.
+   * Base URL prepended to every request URL. When omitted, falls back to the
+   * adapter's server URL (typically `servers[0].url`).
    */
   baseURL?: string
   /**
-   * Group the Cypress requests based on the provided name.
+   * Split generated files into subfolders based on the operation's tag.
    */
   group?: Group
   /**
-   * Tags, operations, or paths to exclude from generation.
+   * Skip operations matching at least one entry in the list.
    */
   exclude?: Array<Exclude>
   /**
-   * Tags, operations, or paths to include in generation.
+   * Restrict generation to operations matching at least one entry in the list.
    */
   include?: Array<Include>
   /**
-   * Override options for specific tags, operations, or paths.
+   * Apply a different options object to operations matching a pattern.
    */
   override?: Array<Override<ResolvedOptions>>
   /**
-   * Override naming conventions for function names and types.
+   * Override how helper names and file paths are built.
    */
   resolver?: Partial<ResolverCypress> & ThisType<ResolverCypress>
   /**
-   * AST visitor to transform generated nodes.
+   * AST visitor applied to each operation node before printing.
    */
   transformer?: ast.Visitor
   /**
-   * Additional generators alongside the default generators.
+   * Custom generators that run alongside the built-in Cypress generators.
    */
   generators?: Array<Generator<PluginCypress>>
 } & ParamsTypeOptions
@@ -95,7 +107,7 @@ type ResolvedOptions = {
   exclude: Array<Exclude>
   include: Array<Include> | undefined
   override: Array<Override<ResolvedOptions>>
-  group: Group | undefined
+  group: Group | null
   baseURL: Options['baseURL'] | undefined
   dataReturnType: NonNullable<Options['dataReturnType']>
   pathParamsType: NonNullable<NonNullable<Options['pathParamsType']>>