@verdaccio/e2e-ui 2.1.1 → 2.3.0

package/build/features.d.ts

@@ -0,0 +1,94 @@
+/// <reference types="cypress" />
+/// <reference types="cypress" />
+/**
+ * Per-test feature flags for enabling/disabling individual test cases
+ * in the e2e-ui suites.
+ *
+ * The Verdaccio UI behaves differently across branches — search result
+ * payload shape differs between the `/-/v1/search` and
+ * `/-/verdaccio/data/search/*` endpoints, the language picker was
+ * added in a specific minor, etc. Rather than forking the suite per
+ * branch, consumers can disable individual tests via
+ * `createRegistryConfig({ features: { … } })`.
+ *
+ * Every flag defaults to `true` (test runs). Override to `false` to
+ * convert the test into a Mocha `it.skip` call — the suite still
+ * reports the test but marks it as pending.
+ */
+export interface Features {
+    search: {
+        /**
+         * Whether to run the "results dropdown renders a matching
+         * package" test. Disable on builds where the search result shape
+         * or the Autocomplete rendering differs from the default assumption.
+         */
+        resultsDropdown: boolean;
+        /**
+         * Whether to run the "clicking a result navigates to detail" test.
+         * Depends on the Autocomplete `onSelectItem` → router wiring.
+         */
+        resultClickNavigation: boolean;
+    };
+    home: {
+        /**
+         * Whether to run the `with a published package` sub-block inside
+         * `homeTests` (publishes a throwaway package and asserts it
+         * renders in the package list).
+         */
+        publishedPackageRendering: boolean;
+    };
+    settings: {
+        /**
+         * Whether to run the "change language via card click" test.
+         * Depends on the `LanguageSwitch` component layout and its
+         * translation sentinels ("Translations", "German"). Skip on
+         * builds that lag behind the upstream translation file.
+         */
+        languageSwitcher: boolean;
+    };
+    signin: {
+        /**
+         * Whether to run the three validation tests (disabled submit
+         * button, invalid credentials error banner). Depends on the
+         * current yup schema and the hard-coded "Invalid username or
+         * password" error string.
+         */
+        validationTests: boolean;
+    };
+    layout: {
+        /**
+         * Whether to run the dark/light theme switch test. Depends on
+         * `web.showThemeSwitch` (defaults to true in ui-theme) and the
+         * `header--button--light` / `header--button--dark` testids.
+         */
+        themeSwitch: boolean;
+    };
+    publish: {
+        /**
+         * Whether to run the "tarball download button fires a GET" test.
+         * Depends on `web.showDownloadTarball` (defaults to true) and
+         * the published package manifest having a valid `dist.tarball`.
+         */
+        downloadTarball: boolean;
+        /**
+         * Whether to run the "raw viewer dialog opens + closes" test.
+         * Depends on `web.showRaw` (defaults to true).
+         */
+        rawViewer: boolean;
+    };
+}
+/** Defaults: all flags on. */
+export declare const DEFAULT_FEATURES: Features;
+import type { DeepPartial } from './testIds';
+/**
+ * Merge user overrides into the default feature flags. Per-section,
+ * one level deep — matching the style of `mergeTestIds`.
+ */
+export declare function mergeFeatures(defaults: Features, overrides?: DeepPartial<Features>): Features;
+/**
+ * Helper that returns either `it` or `it.skip` depending on an
+ * enabled flag. Usage:
+ *
+ *   maybeIt(features.search.resultsDropdown)('…', () => { … });
+ */
+export declare function maybeIt(enabled: boolean): Mocha.TestFunction | Mocha.PendingTestFunction;

package/build/index.d.ts

@@ -1,9 +1,26 @@
 /// <reference types="cypress" />
 import { RegistryConfig, VerdaccioUiOptions } from './types';
-export type { RegistryConfig, VerdaccioUiOptions } from './types';
-export { homeTests, signinTests, publishTests } from './tests';
+export type { RegistryConfig, RegistryTaskResult, VerdaccioUiOptions, } from './types';
+export type { PublishPackageInput, PublishPackageTaskInput, PublishPackageResult, UnpublishPackageInput, UnpublishPackageResult, } from './tasks';
+export type { DeepPartial, Selectors, TestIds } from './testIds';
+export type { Features } from './features';
+export { DEFAULT_SELECTORS, DEFAULT_TEST_IDS } from './testIds';
+export { DEFAULT_FEATURES, maybeIt } from './features';
+export { publishPackage, cleanupPublished, unpublishPackage } from './tasks';
+export { homeTests, signinTests, publishTests, searchTests, settingsTests, layoutTests, } from './tests';
 /**
  * Build a full RegistryConfig from user-provided options with defaults.
+ *
+ * `testIds` and `selectors` are deep-merged per section with the
+ * defaults in `./testIds`. Consumers targeting a non-default Verdaccio
+ * build can override just the fields that drifted:
+ *
+ *   createRegistryConfig({
+ *     registryUrl: 'http://localhost:4873',
+ *     testIds: {
+ *       header: { settingsTooltip: 'my-new-settings-btn' },
+ *     },
+ *   });
  */
 export declare function createRegistryConfig(options: VerdaccioUiOptions): RegistryConfig;
 /**

package/build/tasks/index.d.ts

@@ -0,0 +1,2 @@
+export { publishPackage, cleanupPublished, unpublishPackage } from './publish';
+export type { PublishPackageInput, PublishPackageTaskInput, PublishPackageResult, UnpublishPackageInput, UnpublishPackageResult, } from './publish';

package/build/tasks/publish.d.ts

@@ -0,0 +1,94 @@
+export interface PublishPackageInput {
+    pkgName: string;
+    version?: string;
+    registryUrl: string;
+    credentials: {
+        user: string;
+        password: string;
+    };
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    /**
+     * When true, append a timestamp suffix to the version so reruns against
+     * a persistent registry don't collide on 403. The suffix is a valid
+     * semver prerelease, e.g. `1.0.0-t1712345678`. Defaults to false.
+     */
+    unique?: boolean;
+}
+/**
+ * Shape of the argument passed to `cy.task('publishPackage', ...)`.
+ *
+ * `registryUrl` and `credentials` are optional here (they fall back to
+ * whatever was configured in `setupVerdaccioTasks`), but `pkgName` is
+ * still required — every publish needs a name.
+ */
+export type PublishPackageTaskInput = Partial<Omit<PublishPackageInput, 'pkgName'>> & {
+    pkgName: string;
+};
+export interface PublishPackageResult {
+    pkgName: string;
+    version: string;
+    tempFolder: string;
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/**
+ * Publish a throwaway npm package to the target Verdaccio registry.
+ *
+ * Flow:
+ *   1. Create a throwaway user via `PUT /-/user/...` and capture its
+ *      legacy auth token. See `obtainLegacyToken` for why.
+ *   2. Scaffold a temp project with `package.json`, `README.md`,
+ *      `index.js`, and an `.npmrc` that includes the token.
+ *   3. Spawn `npm publish` from that temp dir.
+ *
+ * `input.credentials` is kept on the signature for forward-compat but
+ * is currently unused — each call mints its own throwaway user.
+ *
+ * Throws on non-zero npm exit. Returns the temp folder path on success
+ * so callers can inspect or clean up.
+ */
+export declare function publishPackage(input: PublishPackageInput): Promise<PublishPackageResult>;
+/**
+ * Remove a temp project folder previously created by publishPackage.
+ * Safe to call with a missing path or a path outside the OS tmp dir —
+ * in the latter case it refuses rather than rm-rf'ing arbitrary paths.
+ */
+export declare function cleanupPublished(tempFolder: string): Promise<void>;
+export interface UnpublishPackageInput {
+    registryUrl: string;
+    pkgName: string;
+    /**
+     * Temp folder returned by a previous `publishPackage` call. If
+     * provided, its existing `.npmrc` (which already carries a legacy
+     * auth token) is reused for the unpublish call — no extra throwaway
+     * user is minted. Otherwise this task creates its own.
+     */
+    tempFolder?: string;
+}
+export interface UnpublishPackageResult {
+    pkgName: string;
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    /**
+     * True if the package was already absent (HTTP 404 from the
+     * registry). Tests typically want to treat this as success.
+     */
+    alreadyGone: boolean;
+}
+/**
+ * Unpublish a package from the target registry so subsequent tests
+ * start from a clean slate.
+ *
+ * If `tempFolder` is provided (typically from a prior `publishPackage`
+ * result), its `.npmrc` is reused so no extra throwaway user is
+ * minted. Otherwise this function creates its own temp folder + token.
+ * Either way the temp folder used by THIS call is removed on exit
+ * (but callers still own the lifecycle of a tempFolder they passed in).
+ *
+ * Treats HTTP 404 / "tarball does not exist" as success so reruns and
+ * parallel teardowns don't flap.
+ */
+export declare function unpublishPackage(input: UnpublishPackageInput): Promise<UnpublishPackageResult>;

package/build/testIds.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Configurable DOM selectors used by the e2e-ui test suites.
+ *
+ * The Verdaccio UI is a moving target — data-testids can and do change
+ * between majors — so every selector referenced by a test lives here
+ * and can be overridden by consumers of `@verdaccio/e2e-ui` via
+ * `createRegistryConfig({ testIds, selectors })`.
+ *
+ * The defaults below match Verdaccio 6.x as of the last time we audited
+ * the ui-components source. If a selector moves, override just the
+ * affected field instead of forking the suite.
+ */
+/**
+ * Map of data-testid values used by the test suites, grouped by UI
+ * section. Each field holds the bare testid string (no `data-testid="…"`
+ * wrapping) — the test helpers pass it through `cy.getByTestId(...)`.
+ */
+export interface TestIds {
+    home: {
+        /** Help card shown on the empty-registry landing page. */
+        helpCard: string;
+        /** 404 "not found" container. */
+        notFound: string;
+    };
+    header: {
+        /** Outermost `<NavBar>` element. */
+        container: string;
+        /** Inner wrapper inside the nav bar. */
+        innerNavBar: string;
+        /** Right-side action cluster wrapper. */
+        right: string;
+        /** Wrapper around the header search input. */
+        searchContainer: string;
+        /** Default SVG Verdaccio logo. */
+        defaultLogo: string;
+        /** Custom (user-provided) logo image. */
+        customLogo: string;
+        /** "Login" button shown when logged out. */
+        loginButton: string;
+        /** Gear icon that opens the settings dialog. */
+        settingsTooltip: string;
+        /** Info icon that opens the registry info dialog. */
+        infoTooltip: string;
+        /**
+         * Theme switch button shown while in LIGHT mode (clicking it
+         * flips to dark). The underlying component swaps between this
+         * and `themeSwitchDark` based on `isDarkMode`.
+         */
+        themeSwitchLight: string;
+        /** Theme switch button shown while in DARK mode. */
+        themeSwitchDark: string;
+        /** Menu icon shown after login (opens the logged-in menu). */
+        logInDialogIcon: string;
+        /** "Log out" entry inside the logged-in menu. */
+        logOutDialogIcon: string;
+        /** "Hi <username>" label inside the logged-in menu. */
+        greetingsLabel: string;
+    };
+    footer: {
+        /** Outer footer wrapper. */
+        container: string;
+        /** "Powered by" version text on the right side of the footer. */
+        version: string;
+    };
+    login: {
+        /** Login dialog container (the MUI Dialog root). */
+        dialog: string;
+        /** DialogContent wrapper inside the login dialog. */
+        dialogContent: string;
+        /**
+         * Error banner shown inside the login dialog when the server
+         * rejects credentials (or any other `errors.root` message the form
+         * sets). Renders inside the `LoginDialogFormError` component.
+         */
+        error: string;
+    };
+    package: {
+        /** Wrapper around the list of packages on the home page. */
+        itemList: string;
+        /** Package name link in the package list (home + search results). */
+        title: string;
+        /** Readme container on the package detail page. */
+        readme: string;
+        /** Sidebar container on the package detail page. */
+        sidebar: string;
+        /** Install commands section list. */
+        installList: string;
+        /** Individual install line for npm. */
+        installNpm: string;
+        /** Individual install line for yarn. */
+        installYarn: string;
+        /** Individual install line for pnpm. */
+        installPnpm: string;
+        /** Keyword list below the install section. */
+        keywordList: string;
+        /** Tab that reveals the dependencies view. */
+        dependenciesTab: string;
+        /** Dependencies list wrapper (one entry per dep). */
+        dependencies: string;
+        /** Tab that reveals the versions view. */
+        versionsTab: string;
+        /** "latest" tag row inside the versions view. */
+        tagLatest: string;
+        /** Tab that reveals the uplinks view. */
+        uplinksTab: string;
+        /** Empty-state message when the package has no uplinks. */
+        noUplinks: string;
+        /** Action-bar tarball download FAB. */
+        downloadTarballBtn: string;
+        /** Action-bar "view raw manifest" FAB. */
+        rawBtn: string;
+        /** Full-screen dialog that opens when `rawBtn` is clicked. */
+        rawViewerDialog: string;
+        /** Close button inside the raw viewer dialog. */
+        closeRawViewer: string;
+    };
+}
+/**
+ * CSS selectors (not data-testids) used by the test suites. These are
+ * things like form-field IDs and framework-specific class names that
+ * Verdaccio's UI exposes as plain selectors rather than testids.
+ */
+export interface Selectors {
+    /** Class applied to the parsed README markdown body. */
+    markdownBody: string;
+    loginDialog: {
+        /** Username text input inside the login dialog. */
+        usernameInput: string;
+        /** Password text input inside the login dialog. */
+        passwordInput: string;
+        /** Submit button inside the login dialog. */
+        submitButton: string;
+    };
+}
+/**
+ * Defaults matching Verdaccio 6.x (bundled ui-theme@9.0.0-next-9.x).
+ * Overridable via `createRegistryConfig({ testIds: { ... } })`.
+ */
+export declare const DEFAULT_TEST_IDS: TestIds;
+/**
+ * Defaults for non-testid CSS selectors. Overridable via
+ * `createRegistryConfig({ selectors: { ... } })`.
+ */
+export declare const DEFAULT_SELECTORS: Selectors;
+/** Deep-partial helper — every field of a nested object becomes optional. */
+export type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+/**
+ * Merge user overrides into the default testIds map. Merging is
+ * per-section (one level deep): `overrides.header` replaces individual
+ * fields under `defaults.header` without touching `defaults.footer`.
+ * The shape is fixed and small, so we enumerate sections by hand
+ * rather than relying on a recursive generic merger.
+ */
+export declare function mergeTestIds(defaults: TestIds, overrides?: DeepPartial<TestIds>): TestIds;
+/** Same idea as `mergeTestIds`, for the CSS-selector block. */
+export declare function mergeSelectors(defaults: Selectors, overrides?: DeepPartial<Selectors>): Selectors;

package/build/tests/index.d.ts

@@ -1,3 +1,6 @@
 export { homeTests } from './home';
 export { signinTests } from './signin';
 export { publishTests } from './publish';
+export { searchTests } from './search';
+export { settingsTests } from './settings';
+export { layoutTests } from './layout';

package/build/tests/layout.d.ts

@@ -0,0 +1,12 @@
+import { RegistryConfig } from '../types';
+/**
+ * Tests for the persistent page chrome: the header (nav bar, logo,
+ * search container, action buttons) and the footer (version marker).
+ * Also asserts that the runtime UI configuration endpoint
+ * `/-/static/ui-options.js` loads successfully — this endpoint emits
+ * `window.__VERDACCIO_BASENAME_UI_OPTIONS`, which the ui-theme relies
+ * on for feature flags like showFooter / showSearch / showSettings. If
+ * it fails the whole SPA degrades to whatever defaults the provider
+ * ships with, so it's worth a direct network-level check.
+ */
+export declare function layoutTests(config: RegistryConfig): void;

package/build/tests/search.d.ts

@@ -0,0 +1,10 @@
+import { RegistryConfig } from '../types';
+/**
+ * UI tests for the Verdaccio search box.
+ *
+ * These tests do NOT depend on any published package — they assert the
+ * search *flow* (input exists, typing triggers the search API, results
+ * region updates) rather than specific package metadata. Tests that need
+ * a real package in the registry should live in publishTests instead.
+ */
+export declare function searchTests(config: RegistryConfig): void;

package/build/tests/settings.d.ts

@@ -0,0 +1,19 @@
+import { RegistryConfig } from '../types';
+/**
+ * Tests for the header Settings dialog and the Translations (language)
+ * picker inside it.
+ *
+ * Requires `web.showSettings: true` in the registry config — the gear
+ * icon only renders when the flag is on (see HeaderRight in Verdaccio's
+ * ui-components package).
+ *
+ * Selector strategy: the language cards in LanguageSwitch do NOT have
+ * data-testids, so this suite leans on:
+ *   - MUI's ARIA roles: `[role="dialog"]`, `[role="tab"]`
+ *   - The stable English labels "Configuration", "Translations",
+ *     "English", "German", and the language description text, which are
+ *     bundled into the ui-theme via `@verdaccio/ui-i18n`
+ *   - The settings trigger's testid from Verdaccio's HeaderToolTipIcon:
+ *     `header--tooltip-settings`
+ */
+export declare function settingsTests(config: RegistryConfig): void;

package/build/types.d.ts

@@ -1,3 +1,9 @@
+/// <reference types="cypress" />
+/// <reference types="cypress" />
+/// <reference types="cypress" />
+import type { Features } from './features';
+import type { PublishPackageResult, PublishPackageTaskInput, UnpublishPackageInput, UnpublishPackageResult } from './tasks';
+import type { DeepPartial, Selectors, TestIds } from './testIds';
 export type RegistryConfig = {
     registryUrl: string;
     port: number;
@@ -6,6 +12,15 @@ export type RegistryConfig = {
         password: string;
     };
     title: string;
+    /** Fully-resolved data-testid map (defaults merged with overrides). */
+    testIds: TestIds;
+    /** Fully-resolved CSS selector map (defaults merged with overrides). */
+    selectors: Selectors;
+    /**
+     * Per-test feature flags — set to `false` to convert a specific
+     * test into `it.skip` without forking the suite.
+     */
+    features: Features;
 };
 export type VerdaccioUiOptions = {
     registryUrl: string;
@@ -15,4 +30,81 @@ export type VerdaccioUiOptions = {
         password: string;
     };
     title?: string;
+    /** Partial override of the default data-testid map. */
+    testIds?: DeepPartial<TestIds>;
+    /** Partial override of the default CSS selector map. */
+    selectors?: DeepPartial<Selectors>;
+    /** Partial override of the default feature flags. */
+    features?: DeepPartial<Features>;
 };
+/**
+ * Return value of the `registry` Cypress task — exposed as a named
+ * type so `cy.task('registry')` can be strongly typed at the call site.
+ */
+export interface RegistryTaskResult {
+    registryUrl: string;
+    port: number;
+}
+declare global {
+    namespace Cypress {
+        interface Chainable<Subject = any> {
+            /**
+             * Find an element by its `data-testid` attribute.
+             */
+            getByTestId(selector: string, ...args: any[]): Chainable<JQuery<HTMLElement>>;
+            /**
+             * Log in to the Verdaccio UI via the login dialog.
+             *
+             * `selectors` is optional — each field falls back to the
+             * Verdaccio 6.x default selector if omitted. Pass overrides when
+             * targeting a non-default Verdaccio build.
+             */
+            login(user: string, password: string, selectors?: {
+                loginButton?: string;
+                usernameInput?: string;
+                passwordInput?: string;
+                submitButton?: string;
+            }): Chainable<void>;
+            /**
+             * Publish a throwaway package to the configured registry.
+             *
+             * @example
+             *   cy.task('publishPackage', {
+             *     pkgName: '@verdaccio/pkg-scoped',
+             *     version: '1.0.0',
+             *     dependencies: { debug: '4.0.0' },
+             *     unique: true,
+             *   }).then((result) => {
+             *     // result is a PublishPackageResult — fully typed.
+             *   });
+             */
+            task(event: 'publishPackage', arg: PublishPackageTaskInput, options?: Partial<Loggable & Timeoutable>): Chainable<PublishPackageResult>;
+            /**
+             * Remove a temp project folder previously returned by
+             * `cy.task('publishPackage', …)`. Refuses to delete paths outside
+             * `os.tmpdir()`. Resolves with `null`.
+             */
+            task(event: 'cleanupPublished', arg: string, options?: Partial<Loggable & Timeoutable>): Chainable<null>;
+            /**
+             * Unpublish a package from the registry so the next test starts
+             * from a clean slate. Accepts either a bare package name (uses
+             * the configured registry URL and mints its own throwaway token)
+             * or a full input object (reuses an existing `tempFolder`'s
+             * .npmrc for efficiency).
+             *
+             * @example
+             *   cy.task('unpublishPackage', '@verdaccio/pkg-scoped');
+             *   cy.task('unpublishPackage', { pkgName, tempFolder });
+             */
+            task(event: 'unpublishPackage', arg: string | (Omit<UnpublishPackageInput, 'registryUrl'> & {
+                registryUrl?: string;
+            }), options?: Partial<Loggable & Timeoutable>): Chainable<UnpublishPackageResult>;
+            /**
+             * Read back the registry URL and port that were passed to
+             * `setupVerdaccioTasks`. Useful in specs that need to compute
+             * URLs without importing the cypress config.
+             */
+            task(event: 'registry', arg?: unknown, options?: Partial<Loggable & Timeoutable>): Chainable<RegistryTaskResult>;
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verdaccio/e2e-ui",
-  "version": "2.1.1",
+  "version": "2.3.0",
   "type": "module",
   "license": "MIT",
   "description": "Cypress plugin for Verdaccio UI e2e tests — run against any registry",