@verdaccio/e2e-ui 2.1.0 → 2.2.0

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,130 @@
+/**
+ * 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;
+        /** 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;
+    };
+    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;
+    };
+}
+/**
+ * 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/home.d.ts

@@ -0,0 +1,2 @@
+import { RegistryConfig } from '../types';
+export declare function homeTests(config: RegistryConfig): void;

package/build/tests/index.d.ts

@@ -0,0 +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/publish.d.ts

@@ -0,0 +1,2 @@
+import { RegistryConfig } from '../types';
+export declare function publishTests(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/tests/signin.d.ts

@@ -0,0 +1,2 @@
+import { RegistryConfig } from '../types';
+export declare function signinTests(config: RegistryConfig): void;

package/build/types.d.ts

@@ -0,0 +1,102 @@
+/// <reference types="cypress" />
+/// <reference types="cypress" />
+/// <reference types="cypress" />
+import type { PublishPackageResult, PublishPackageTaskInput, UnpublishPackageInput, UnpublishPackageResult } from './tasks';
+import type { DeepPartial, Selectors, TestIds } from './testIds';
+export type RegistryConfig = {
+    registryUrl: string;
+    port: number;
+    credentials: {
+        user: string;
+        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;
+};
+export type VerdaccioUiOptions = {
+    registryUrl: string;
+    port?: number;
+    credentials?: {
+        user: string;
+        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>;
+};
+/**
+ * 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.0",
+  "version": "2.2.0",
   "type": "module",
   "license": "MIT",
   "description": "Cypress plugin for Verdaccio UI e2e tests — run against any registry",