@open-xchange/appsuite-codeceptjs 0.7.0 → 0.7.2

package/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(find:*)",
+      "Bash(grep:*)",
+      "Bash(npm view:*)"
+    ]
+  }
+}

package/index.d.ts

@@ -0,0 +1,598 @@
+/**
+ * @copyright Copyright (c) Open-Xchange GmbH, Germany <info@open-xchange.com>
+ * @license AGPL-3.0
+ *
+ * This code is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with OX App Suite. If not, see <https://www.gnu.org/licenses/agpl-3.0.txt>.
+ *
+ * Any use of the work other than as authorized under this license or copyright law is prohibited.
+ */
+
+declare module '@open-xchange/appsuite-codeceptjs' {
+
+  import Helper from '@codeceptjs/helper'
+  import { Page, Browser, BrowserContext, Request, Response } from 'playwright-core'
+  import * as OXPO from '@open-xchange/appsuite-codeceptjs-pageobjects'
+
+  export { recorder, event as codeceptEvents } from 'codeceptjs'
+
+  // util ---------------------------------------------------------------------
+
+  /**
+   * Converts the return type `Promise<void>` of all methods in `T` to `void`.
+   *
+   * @template T
+   *  The interface with methods to be converted.
+   */
+  export type SyncifyVoidMethods<T> = {
+    [K in keyof T]: T[K] extends (...args: infer A) => Promise<infer R> ? R extends void ? (...args: A) => void : T[K] : T[K]
+  }
+
+  class PropagatedError extends Error {
+    constructor (error: Error)
+  }
+
+  export type { PropagatedError }
+
+  export const util: {
+    getLoginTimeout (): number
+    getURLRoot (): string
+    getServerURL (): string
+    getJavascriptRoot (): string
+    userContextId (): number
+    admin (): string
+    mxDomain (): string
+    smtpServer (): string
+    imapServer (): string
+    getDefaultUserPassword (): string
+    PropagatedError: typeof PropagatedError
+    addJitter (id: number): number
+  }
+
+  // config -------------------------------------------------------------------
+
+  export interface AppSuiteCodeceptConfig extends CodeceptJS.MainConfig {
+    helpers: NonNullable<CodeceptJS.MainConfig['helpers']>
+    include: NonNullable<CodeceptJS.MainConfig['include']>
+    plugins: NonNullable<CodeceptJS.MainConfig['plugins']>
+  }
+
+  export const config: AppSuiteCodeceptConfig
+
+  // contexts -----------------------------------------------------------------
+
+  export interface UserAttributes {
+    entries: Array<{ key: string; value: unknown }>
+  }
+
+  export interface ContextData {
+    enabled: boolean
+    filestoreId: number
+    filestore_name: string
+    id: number
+    loginMappings: string[]
+    maxQuota: number
+    name: string
+    userAttributes: UserAttributes
+  }
+
+  export interface AuthData {
+    login: string
+    password: string
+  }
+
+  export interface ContextAdmin extends AuthData {
+    display_name: string
+    email1: string
+    given_name: string
+    name: string
+    primaryEmail: string
+    sur_name: string
+  }
+
+  export type ModuleAccess = Record<string, boolean>
+
+  class Context {
+    readonly id: number
+    readonly ctxdata: ContextData
+    readonly admin: ContextAdmin
+    readonly auth: AuthData
+    constructor (options: { ctxdata: ContextData; admin: ContextAdmin; auth: AuthData })
+    remove (): Promise<void>
+    hasConfig (key: string, value: unknown): Promise<void>
+    hasCapability (capability: string): Promise<void>
+    doesntHaveCapability (capability: string): Promise<void>
+    hasAccessCombination (accessCombinationName: string): Promise<void>
+    getModuleAccess (): Promise<ModuleAccess>
+    hasModuleAccess (moduleAccess: ModuleAccess): Promise<void>
+    hasQuota (maxQuota: number): Promise<void>
+  }
+
+  export type { Context }
+
+  export interface Contexts extends ReadonlyArray<Context> {
+    create (ctx?: { filestoreId?: number; id?: string; maxQuota?: number }): Promise<Context>
+    reuse (ctx: Context, admin?: ContextAdmin, auth?: AuthData): Promise<Context>
+    removeAll (auth?: AuthData): Promise<void>
+  }
+
+  // users --------------------------------------------------------------------
+
+  export interface UserData {
+    aliases: string[]
+    contextadmin: boolean
+    defaultSenderAddress: string
+    display_name: string
+    email1: string
+    given_name: string
+    id: number
+    imapLogin: string
+    imapPort: number
+    imapSchema: string
+    imapServer: string
+    imapServerString: string
+    language: string
+    mailenabled: boolean
+    name: string
+    password: string
+    passwordMech: string
+    password_expired: boolean
+    primaryEmail: string
+    smtpPort: number
+    smtpSchema: string
+    smtpServer: string
+    smtpServerString: string
+    sur_name: string
+    userAttributes: UserAttributes
+    convert_drive_user_folders: boolean
+  }
+
+  class User {
+    readonly userdata: UserData
+    readonly context: Context
+    constructor (options: { user: UserData, context: Context })
+    remove (): Promise<void>
+    hasConfig (key: string, value: unknown): Promise<void>
+    hasAlias (alias: string): Promise<void>
+    doesntHaveAlias (alias: string): Promise<void>
+    hasAccessCombination (accessCombinationName: string): Promise<void>
+    getModuleAccess (): Promise<ModuleAccess>
+    hasModuleAccess (moduleAccess: ModuleAccess): Promise<void>
+    hasCapability (capability: string): Promise<void>
+    doesntHaveCapability (capability: string): Promise<void>
+    login (): string
+    get <K extends keyof UserData> (param: K): UserData[K]
+    toJSON (): UserData & { context: ContextData & { admin: ContextAdmin; auth: AuthData } }
+  }
+
+  export type { User }
+
+  export interface Users extends ReadonlyArray<User> {
+    getRandom (user?: Partial<UserData>): Partial<UserData>
+    create (user?: Partial<UserData>, context?: Context): Promise<User>
+    change (userdata: Partial<UserData>): Promise<void>
+    removeAll (): Promise<void>
+  }
+
+  // shared accounts ----------------------------------------------------------
+
+  export interface SharedAccountData {
+    imapServer: string
+    smtpServer: string
+    language: string
+    mailenabled: number
+    name: string
+    display_name: string
+    imapLogin: string
+    primaryEmail: string
+    email1: string
+    timezone: string
+    password: string
+  }
+
+  export type SharedAccountCapability = 'sendAs' | 'sendOnBehalf' | 'snippets' | 'writeSnippets' | 'manageSieve'
+
+  export interface SharedAccountModuleConfig {
+    permissionLevel: 'viewer' | 'editor' | 'author' | 'admin'
+    grantedCapability: SharedAccountCapability[]
+    deniedCapability: SharedAccountCapability[]
+  }
+
+  class SharedAccount {
+    readonly sharedAccountData: SharedAccountData
+    readonly context: Context
+    constructor (options: { sharedAccountData: SharedAccountData, context: Context })
+    createPermissions (options?: { users?: User[], groups?: User[], mail?: SharedAccountModuleConfig, calendar?: SharedAccountModuleConfig }): Promise<void>
+    getFullId (): string
+    getData (): Promise<SharedAccountData>
+    remove (): Promise<void>
+    toJSON (): SharedAccountData & { context: ContextData & { admin: ContextAdmin; auth: AuthData } }
+  }
+
+  export type { SharedAccount }
+
+  export interface SharedAccounts extends ReadonlyArray<SharedAccount> {
+    getRandom (): SharedAccountData
+    create (sharedAccountData?: Partial<SharedAccountData>, ctx?: Context): Promise<SharedAccount>
+    getDefaultConfig (): { permissionLevel: string; grantedCapability: string[]; deniedCapability: string[] }
+    list (context: Context): Promise<SharedAccountData[]>
+  }
+
+  // event --------------------------------------------------------------------
+
+  export interface AppSuiteCodeceptEventMap {
+    'provisioning.user.create': [user: UserData, context: Context]
+    'provisioning.user.created': [user: User]
+    'provisioning.user.removed': [user: User]
+    'provisioning.context.create': [context: ContextData, admin: ContextAdmin, auth: AuthData]
+    'provisioning.context.created': [context: Context]
+    'provisioning.context.removed': [context: Context]
+  }
+
+  export const event: {
+    readonly provisioning: {
+      readonly user: {
+        readonly create: 'provisioning.user.create'
+        readonly created: 'provisioning.user.created'
+        readonly removed: 'provisioning.user.removed'
+      }
+      readonly context: {
+        readonly create: 'provisioning.context.create'
+        readonly created: 'provisioning.context.created'
+        readonly removed: 'provisioning.context.removed'
+      }
+    }
+    dispatcher: NodeJS.EventEmitter<AppSuiteCodeceptEventMap>
+    emit <K extends keyof AppSuiteCodeceptEventMap> (event: K, ...params: AppSuiteCodeceptEventMap[K]): void
+  }
+
+  // helper -------------------------------------------------------------------
+
+  export interface UserOptions {
+    /**
+     * The user account to be used. Default is the first created user.
+     * @default users[0]
+     */
+    user?: User
+  }
+
+  export type MailAddress = [name: string, address: string]
+
+  export interface MailAttachment {
+    id?: string
+    content_type: string
+    content?: string
+    filename?: string
+    size?: number
+    disp?: 'inline' | 'attachment' | 'alternative'
+  }
+
+  export interface MailSecurity {
+    encrypt?: boolean
+    sign?: boolean
+    type?: 'pgp' | 'smime'
+  }
+
+  export interface HaveMailData {
+    folder?: string
+    from: MailAddress[]
+    to: MailAddress[]
+    subject?: string
+    sendtype: number
+    attachments?: MailAttachment[]
+    security?: MailSecurity
+  }
+
+  export interface HaveMailFromFile {
+    folder?: string
+    path: string
+  }
+
+  export interface GrabDefaultFolderOptions extends UserOptions {
+    type?: string
+  }
+
+  export interface HaveFileData {
+    filename: string
+    contents: BlobPart
+  }
+
+  export interface HaveFileOptions extends UserOptions {
+    cryptoAction?: 'encrypt'
+  }
+
+  export interface AppSuiteHelper extends Helper {
+    waitForDownload (locator: string, filename: string, referenceFilePath?: string): Promise<void>
+    grabAxeReport (options?: { disableRules?: string | string[]; exclude?: string | string[]; include?: string | string[] }): Promise<object>
+    selectFolder (id: string, context?: string): Promise<void>
+    throttleNetwork (networkConfig: 'OFFLINE' | 'GPRS' | '2G' | '3G' | '4G' | 'DSL' | 'ONLINE'): Promise<void>
+    haveSetting (settings: Record<string, unknown>, options?: UserOptions): Promise<void>
+    haveSetting (key: string, value: unknown, options?: UserOptions): Promise<void>
+    /**
+     * Changes a configuration item of a user account during a test.
+     *
+     * Use this method inside test scenarios instead of calling `await
+     * user.hasConfig()` directly to make this call part of the recorder queue,
+     * instead of executing it immediately during test step registration.
+     *
+     * @param key
+     *  The configuration key.
+     *
+     * @param value
+     *  The new configuration value.
+     *
+     * @param options
+     *  Optional parameters.
+     */
+    haveConfig (key: string, value: unknown, options?: UserOptions): Promise<void>
+    /**
+     * Adds a capability to a user account during a test.
+     *
+     * Use this method inside test scenarios instead of calling `await
+     * user.hasCapability()` directly to make this call part of the recorder
+     * queue, instead of executing it immediately during test step registration.
+     *
+     * @param capability
+     *  The capability to be added to the user account.
+     *
+     * @param options
+     *  Optional parameters.
+     */
+    haveCapability (capability: string, options?: UserOptions): Promise<void>
+    /**
+     * Removes a capability from a user account during a test.
+     *
+     * Use this method inside test scenarios instead of calling `await
+     * user.doesntHaveCapability()` directly to make this call part of the
+     * recorder queue, instead of executing it immediately during test step
+     * registration.
+     *
+     * @param capability
+     *  The capability to be removed from the user account.
+     *
+     * @param options
+     *  Optional parameters.
+     */
+    dontHaveCapability (capability: string, options?: UserOptions): Promise<void>
+    /**
+     * Changes the access combination of a user account during a test.
+     *
+     * Use this method inside test scenarios instead of calling `await
+     * user.hasAccessCombination()` directly to make this call part of the
+     * recorder queue, instead of executing it immediately during test step
+     * registration.
+     *
+     * @param accessCombination
+     *  The access combination to be set at the user account.
+     *
+     * @param options
+     *  Optional parameters.
+     */
+    haveAccessCombination (accessCombination: string, options?: UserOptions): Promise<void>
+    /**
+     * Changes the module access flags of a user account during a test.
+     *
+     * Use this method inside test scenarios instead of calling `await
+     * user.hasModuleAccess()` directly to make this call part of the recorder
+     * queue, instead of executing it immediately during test step
+     * registration.
+     *
+     * @param moduleAccess
+     *  The module access flags to be set at the user account.
+     *
+     * @param options
+     *  Optional parameters.
+     */
+    haveModuleAccess (moduleAccess: ModuleAccess, options?: UserOptions): Promise<void>
+    haveSnippet (snippet: object /* TODO */, options?: UserOptions): Promise<void>
+    haveMail (data: HaveMailData | HaveMailFromFile, options?: UserOptions): Promise<void>
+    haveMails (iterable: Iterable<HaveMailData | HaveMailFromFile>, options?: UserOptions): Promise<void>
+    /**
+     * Adds an alias email address to a user account during a test.
+     *
+     * Use this method inside test scenarios instead of calling `await
+     * user.hasAlias()` directly to make this call part of the recorder queue,
+     * instead of executing it immediately during test step registration.
+     *
+     * @param alias
+     *  The alias email address to be added to the user account.
+     *
+     * @param options
+     *  Optional parameters.
+     */
+    haveAnAlias (alias: string, options?: UserOptions): Promise<void>
+    /**
+     * Removes an alias email address from a user account during a test.
+     *
+     * Use this method inside test scenarios instead of calling `await
+     * user.doesntHaveAlias()` directly to make this call part of the recorder
+     * queue, instead of executing it immediately during test step registration.
+     *
+     * @param alias
+     *  The alias email address to be removed from the user account.
+     *
+     * @param options
+     *  Optional parameters.
+     */
+    dontHaveAlias (alias: string, options?: UserOptions): Promise<void>
+    haveMailFilterRule (rule: object /* TODO */, options?: UserOptions): Promise<void>
+    haveFolder (folder: { title: string; module: string; parent: string; permissions?: string[]; subscribed?: number }, options?: UserOptions): Promise<string>
+    haveContact (contact: object /* TODO */, options?: UserOptions): Promise<object> /* TODO */
+    grabDefaultFolder (module: string, options?: GrabDefaultFolderOptions): Promise<string>
+    /**
+     * Uploads a file to a specified folder.
+     * @param folderId - The ID of the folder where the file will be uploaded.
+     * @param file - The path to the file or an object containing the file information.
+     * @param options - Additional options for the file upload.
+     * @returns - The uploaded file data.
+     */
+    haveFile(folderId: string, file: string | HaveFileData, options?: HaveFileOptions): Promise<{ folder_id: string; id: string }>
+    haveTask (task: object /* TODO */, options?: UserOptions): Promise<object> /* TODO */
+    /**
+     * Uploads an attachment to the specified module and object.
+     * @param module - The module to attach the file to.
+     * @param obj - The object to attach the file to.
+     * @param file - The file to be attached.
+     * @param options - The options for creating the HTTP client.
+     */
+    haveAttachment (module: 'calendar' | 'chronos' | 'contacts' | 'drive' | 'files' | 'infostore' | 'tasks', obj: object /** TODO */, file: string, options?: UserOptions): Promise<object> /* TODO */
+    haveAppointment (appointment: object /* TODO */, options?: UserOptions): Promise<object> /* TODO */
+    importAppointment (data: { sourcePath: string; folder?: string }, options?: UserOptions): Promise<object> /* TODO */
+    haveResource (data: object /* TODO */, options?: UserOptions): Promise<string>
+    dontHaveResource (pattern: object /* TODO */, options?: UserOptions): Promise<Array<{ id: string; pattern: object }>>
+    haveGroup (group: object /* TODO */, options?: UserOptions): Promise<object> /* TODO */
+    dontHaveGroup (name: string, options?: UserOptions): Promise<Array<{ id: string; name: string }>>
+    haveLockedFile (data: object /* TODO */, options?: UserOptions): Promise<object> /* TODO */
+    setMailCategories (data: { mailId: string; folder: string; categories: string[] }, options?: UserOptions): Promise<object> /* TODO */
+    pressKeys (text: string): Promise<void>
+    /**
+     * @param options
+     * @param [options.user]                 a user object as returned by provisioning helper, default is the "first" user
+     * @param [options.additionalAccount]    an additional user that will be provisioned as the external account
+     * @param [options.extension]            optional extension added to the mail address ("ext" will be translated to: $user.primary+ext@mailDomain)
+     * @param [options.name]                 name of the account
+     * @param [options.transport_auth]       transport authentication, default: 'none'
+     */
+    haveMailAccount (options?: { user?: object, additionalAccount?: object, extension?: string, name?: string, transport_auth?: string }): Promise<object> /* TODO */
+    waitForSetting (obj: object, timeout?: number, options?: UserOptions): Promise<void>
+    waitForCapability (capability: string, timeout?: number, options?: UserOptions & { shouldBe?: boolean }): Promise<void>
+    copyToClipboard (): Promise<void>
+    getClipboardContent (): Promise<string>
+    createGenericFile (filename: string, size: number): Promise<void>
+  }
+
+  export interface AppSuiteHelpers {
+    Playwright: CodeceptJS.Playwright
+    AppSuite: AppSuiteHelper
+  }
+
+  // actor --------------------------------------------------------------------
+
+  export interface LoginOptions extends UserOptions {
+    wait?: boolean
+    isDeepLink?: boolean
+  }
+
+  export interface AppSuiteActor {
+    amOnLoginPage (): void
+    openApp (appName: CodeceptJS.LocatorOrString): void
+    waitForApp (): void
+    /**
+     * This simplifies the input of mail addresses into input fields.
+     * There must be an array of users defined in the AppSuite helper configuration.
+     * If you want to fill in a mailaddress of such a user you can simply use this function.
+     *
+     * @param locator - the selector of an editable field
+     * @param userIndex - the users position in the users array provided via helper config
+     */
+    insertMailaddress (locator: CodeceptJS.LocatorOrString, userIndex: number): void
+    /**
+     * Logs in the user with the specified URL parameters and options.
+     * If the URL parameters are an object, it will be converted to an empty array.
+     * The options parameter is an object that can contain a 'user' property.
+     * If the 'user' property is not provided, the first user from the 'users' container will be used.
+     * The login process includes making an API request to the login endpoint with the user's credentials.
+     * After successful login, the page will be navigated to the specified URL with the URL parameters.
+     * If the 'isDeepLink' option is true, the URL will be constructed with a '#' prefix.
+     * The login process also includes waiting for the page to load and checking for the presence of the app.
+     * @param urlParams - The URL parameters as an array or object.
+     * @param options - The login options.
+     */
+    login(urlParams: string | string[], options?: LoginOptions): void
+    login(options?: LoginOptions): void
+    logout(): void
+    waitForNetworkTraffic (): void
+    /**
+     * Waits for the specified element to receive focus.
+     * @param selector - The locator of the element. Only accepts css selectors.
+     */
+    waitForFocus (selector: string): void
+    triggerRefresh (): void
+    grabBackgroundImageFrom (locator: CodeceptJS.LocatorOrString): Promise<string>
+    clickDropdown (text: string): void
+    clickToolbar (selector: string, timeout?: number): void
+    clickPrimary (text: string): void
+    openFolderMenu (folderName: string): void
+    changeTheme (options: { theme: string }): void
+    /**
+     * Selects the text in a text field or contenteditable element from cursor position to beginning of line.
+     */
+    selectLine (): void
+  }
+
+  export const actor: CodeceptJS.actor
+
+  // augment global CodeceptJS interfaces -------------------------------------
+
+  global {
+    namespace CodeceptJS {
+
+      // Playwright interface fixes
+      interface Playwright {
+        /** The browser object. */
+        readonly browser: Browser
+        /** The browser context object. */
+        readonly browserContext: BrowserContext
+        /** The page object for the current (active) page in the browser. */
+        readonly page: Page
+
+        // fix for non-generic `any` signature
+        usePlaywrightTo(description: string, callback: (playwright: Playwright) => void | Promise<void>): void
+        usePlaywrightTo<R>(description: string, callback: (playwright: Playwright) => R | Promise<R>): Promise<R>
+
+        // fix for non-generic `any` signature
+        executeScript(callback: (this: void) => void | Promise<void>): void
+        executeScript<T>(callback: (this: void, arg: T) => void | Promise<void>, arg: T): void
+        executeScript<R>(callback: (this: void) => R | Promise<R>): Promise<R>
+        executeScript<T, R>(callback: (this: void, arg: T) => R | Promise<R>, arg: T): Promise<R>
+
+        // fix for `any` callback signature
+        waitForRequest(urlOrPredicate: string | ((request: Request) => boolean), sec?: number): void
+        waitForResponse(urlOrPredicate: string | ((response: Response) => boolean), sec?: number): void
+      }
+
+      // helpers and actor methods for `I` object added by this plugin
+      interface Methods extends
+        SyncifyVoidMethods<Playwright>,
+        SyncifyVoidMethods<AppSuiteHelper>,
+        AppSuiteActor { }
+
+      // CodeceptJS does not add `Methods` to `I` by itself
+      interface I extends Methods { }
+
+      // additional fragments and page objects
+      interface SupportObject {
+        autocomplete: OXPO.ContactAutoCompleteFragment
+        calendar: OXPO.CalendarPageObject
+        contactpicker: OXPO.ContactPickerFragment
+        contacts: OXPO.ContactsPageObject
+        contexts: Contexts
+        dialogs: OXPO.DialogsFragment
+        drive: OXPO.DrivePageObject
+        mail: OXPO.MailPageObject
+        mailfilter: OXPO.SettingsMailFilterFragment
+        mobileCalendar: OXPO.MobileCalendarPageObject
+        mobileContacts: OXPO.MobileContactsPageObject
+        mobileMail: OXPO.MobileMailPageFragment
+        search: OXPO.SearchFragment
+        settings: OXPO.SettingsFragment
+        sharedaccounts: SharedAccounts
+        tasks: OXPO.TasksPageObject
+        tinymce: OXPO.TinyMceFragment
+        topbar: OXPO.TopBarFragment
+        users: Users
+        viewer: OXPO.ViewerFragment
+      }
+    }
+  }
+}

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@open-xchange/appsuite-codeceptjs",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "OX App Suite CodeceptJS Configuration and Helpers",
   "main": "index.js",
+  "types": "index.d.ts",
   "bin": {
     "e2e-rerun": "./customRerun.js"
   },
@@ -17,7 +18,7 @@
     "@axe-core/playwright": "^4.11.0",
     "@codeceptjs/helper": "^2.0.4",
     "@influxdata/influxdb-client": "^1.35.0",
-    "@open-xchange/appsuite-codeceptjs-pageobjects": "^1.1.0",
+    "@open-xchange/appsuite-codeceptjs-pageobjects": "^1.1.1",
     "@playwright/test": "1.58.2",
     "allure-codeceptjs": "2.15.1",
     "chai": "^6.2.1",
@@ -34,7 +35,7 @@
     "playwright-core": "1.58.2",
     "short-uuid": "^6.0.3",
     "@open-xchange/codecept-horizontal-scaler": "0.1.14",
-    "@open-xchange/soap-client": "0.0.11"
+    "@open-xchange/soap-client": "0.0.12"
   },
   "devDependencies": {
     "@types/node": "^24.10.3",

package/global.d.ts

@@ -1,3 +0,0 @@
-/* eslint-disable camelcase */
-declare const codecept_dir: string
-declare const output_dir: string