diff --git a/README.md b/README.md
index 6890fd1..7921aa9 100644
--- a/README.md
+++ b/README.md
@@ -1,775 +1,938 @@
# Joomla Cypress
+
+
+[![version][version-badge]][package]
+
+
This is a support package that helps in writing end-to-end tests for the [Joomla CMS](https://joomla.org) and its extensions with the frontend testing tool [Cypress](/https://www.cypress.io/).
-All active Joomla development [branches](https://github.com/joomla/joomla-cms/branches) are supported.
+The Joomla default branch and all active development [branches](https://github.com/joomla/joomla-cms/branches) are supported.
+
+## Installation
+
+`joomla-cypress` is distributed with [npm](https://npmjs.com/) and works with the latest version of Cypress.
+It should be installed as one of your project's `devDependencies`:
+```
+npm install --save-dev @testing-library/joomla-cypress
+```
+
+## Usage
+
+To import and load the additional Cypress custom commands you will typically extend the `cypress/support/index.js` file:
+```
+// Add attachFile() command, which is used in installExtensionFromFileUpload()
+import 'cypress-file-upload';
+
+// Register Joomla Cypress custom commands from npm module 'joomla-cypress'
+import { registerCommands } from "joomla-cypress";
+registerCommands();
+```
## Cypress Custom Commands for Joomla
The Cypress API is extended with [custom commands](https://docs.cypress.io/api/cypress-api/custom-commands).
+As Cypress custom commands, all `joomla-cypress` extended commands return an `Cypress.Chainable`.
+
+The target Joomla installation requires the language `en-GB` for the used Joomla administrator user.
+
+All added commands use Cypress logging, with messages formatted in bold type at the beginning and
+double hyphens at the end.
+These log messages can be observed when running the Cypress GUI.
+This consistent logging format helps to easily identify the steps and
+status of the custom commands during test execution. For example:
+
+**Install an extension from file upload**
+...
+--Install an extension from file upload--
+
The Cypress custom commands for Joomla are grouped into the following categories:
-* Common
-* Extensions
-* Joomla
-* Support
-* User
+* User Commands
+* Joomla Commands
+* Extensions Commands
+* Support Commands
+* Common Commands
-:point_right: If you would like to see the complete list of custom commands, you can use the TOC button at the top right of the README.
+:point_right: If you would like to see the complete list of custom commands as overview,
+on GitHub you can use the TOC button at the top right of the README.
-### Common Commands
+### User Commands
-#### iframe
+#### `doAdministratorLogin`
-**Command**
+The command `doAdministratorLogin` initiates the administrator login process for the backend.
+It performs the administrator login with the specified login information or with the Cypress environment variables.
+The user must be a member of the 'Manager', 'Administrator' or 'Super Users' group to be able to log in to the backend.
-Command to interact with iframes in Cypress, ensuring they are fully loaded before proceeding with assertions or actions.
+By default, a [Cypress session](https://docs.cypress.io/api/commands/session) is used
+to cache and restore session data for this user's backend login across Cypress test specs.
+This speeds up the entire test suite.
-```
-Cypress.Commands.add('iframe', {prevSubject: 'element'}, $iframes => new Cypress.Promise(resolve => {...}));
+See also [doAdministratorLogout](#doadministratorlogout) and [doFrontendLogin](#dofrontendlogin).
+
+##### Usage
+
+```javascript
+cy.doAdministratorLogin(user, password, useSnapshot)
```
-**Function**
+##### Arguments
-Function to check if an iframe is fully loaded and then resolve with its body content for Cypress commands.
+- **`user`** *(string, optional, default: `Cypress.env('username')`)*: The username for logging in.
+- **`password`** *(string, optional, default: `Cypress.env('password')`)*: The password for logging in.
+- **`useSnapshot`** *(boolean, optional, default: `true`)*:
+ Boolean flag to determine if this users backend login session should be cached across specs.
-```
-const isIframeLoaded = $iframe => {...};
-```
+##### Example
-**Variables**
+```javascript
+// Admin login without saving the session
+cy.doAdministratorLogin("admin-user", "admin-user-password", false);
+```
-- `$iframe`: \
-Represents the iframe element being processed. \
-Used to manage the iframe's loading state and retrieve its content once loaded.
+---
-### Extensions Commands
+#### `doAdministratorLogout`
-#### installExtensionFromFolder
+The command `doAdministratorLogout` initiates user logout process from the backend.
+All session data (both backend and frontend, for all users) is being cleaned up.
+A user must be logged into the backend.
-**Command**
+See also [doAdministratorLogin](#doadministratorlogin).
-Installs a Joomla extension from a folder
+##### Usage
-```
-Cypress.Commands.add('installExtensionFromFolder', installExtensionFromFolder);
+```javascript
+cy.doAdministratorLogout()
```
-**Function**
+##### Example
-Installs an extension in Joomla that is located in a folder inside the server.
-```
-const installExtensionFromFolder = (path, type = 'Extension') => {...};
+```javascript
+// Do explicit logout to start with new login
+cy.doAdministratorLogout();
+// Check login action log
+cy.doAdministratorLogin("admin-user", "admin-user-password")
+ .visit('/administrator/index.php?option=com_actionlogs&view=actionlogs')
+ .contains('User admin-user logged in to admin');
```
-**Variables**
+---
-- `path`: \
- The path to the folder where the extension is located.
-- `type`: \
- The type of extension (default is 'Extension').
+#### `doFrontendLogin`
----
+The command `doFrontendLogin` initiates a user login to the frontend.
+It performs the user login with the specified login information or with the Cypress environment variables.
+The user must belong to a user group that has the necessary permissions to access the frontend.
-#### installExtensionFromUrl
+By default, [Cypress session](https://docs.cypress.io/api/commands/session) is used
+to cache and restore session data for this users frontend login across Cypress test specs.
+This speeds up the entire test suite.
-**Command**
+See also [doFrontendLogout](#dofrontendlogout) and [doAdministratorLogin](#doadministratorlogin).
-Installs a Joomla extension from a URL
-```
-Cypress.Commands.add('installExtensionFromUrl', installExtensionFromUrl);
+##### Usage
+
+```javascript
+cy.doFrontendLogin(user, password, useSnapshot)
```
-**Function**
+##### Arguments
-Installs an extension in Joomla that is located at a URL.
-```
-const installExtensionFromUrl = (url, type = 'Extension') => {...};
-```
+- **`user`** *(string, optional, default: `Cypress.env('username')`)*: The user name for logging in.
+- **`password`** *(string, optional, default: `Cypress.env('password')`)*: The password for logging in.
+- **`useSnapshot`** *(boolean, optional, default: `true`)*:
+ Boolean flag to determine if this users frontend login session should be cached across specs.
+
+##### Example
-**Variables**
+```javascript
+// Checks the welcome message with the user's name
+cy.doFrontendLogin()
+ .visit("/")
+ .contains(`Hi ${Cypress.env('name')}`).should('be.visible');
+```
-- `url`: \
- The URL where the extension is located.
-- `type`: \
- The type of extension (default is 'Extension').
-
---
-#### installExtensionFromFileUpload
+#### `doFrontendLogout`
-**Command**
+The command `doFrontendLogout` initiates frontend logout process.
+All session data (both backend and frontend, for all users) is being cleaned up.
+A user must be logged into the frontend.
-```
-Cypress.Commands.add('installExtensionFromFileUpload', installExtensionFromFileUpload);
-```
+See also [doFrontendLogin](#dofrontendlogin).
-**Function**
+##### Usage
+```javascript
+cy.doFrontendLogin()
```
-import 'cypress-file-upload';
-const installExtensionFromFileUpload = (file, type = 'Extension') => {...};
+
+##### Example
+
+```javascript
+// Can log in and out with the default credentials
+cy.doFrontendLogin(null, null, false)
+ .doFrontendLogout();
```
-**Variables**
-- `file`: \
- The file to be uploaded.
-- `type`: \
- The type of extension (default is 'Extension').
-
---
-#### uninstallExtension
+#### `createUser`
-**Command**
+The command `createUser` creates a new user entry in Joomla.
+If the user name already exists, the creation will fail.
+The user entry is activated after creation.
-```
-Cypress.Commands.add('uninstallExtension', uninstallExtension);
-```
-**Function**
+##### Usage
+```javascript
+cy.createUser(name, username, password, email, userGroup)
```
-const uninstallExtension = (extensionName) => {...};
+
+##### Arguments
+
+- **`name`** *(string)*: The full name of the user.
+- **`username`** *(string)*: The name the user will log in as.
+- **`password`** *(string)*: The user's password.
+- **`email`** *(string)*: The user's email address.
+- **`userGroup`** *(string, optional, default: 'Super Users')*: The user group that is assigned to the new user entry.
+
+##### Example
+
+```javascript
+cy.doAdministratorLogin()
+ .createUser("Alice in Wonderland", "alice", "CheshireSmile", "alice@in.wonderland");
```
-**Variables**
-- `extensionName`: \
- The name of the extension to be uninstalled.
-
---
-#### installLanguage
+### Joomla Commands
-**Command**
+#### `installJoomla`
-```
-Cypress.Commands.add('installLanguage', installLanguage);
-```
-**Function**
+After Joomla download, the command `installJoomla` runs all 'Joomla Installer' steps
+to install a Joomla instance on a web server.
+The installed language pack 'en-GB' is English (United Kingdom).
+After the command, the 'Joomla Installer' screen remains open in the session.
+:warning: The `/installation` folder is not deleted after the installation.
+This allows multiple runs of the command `installJoomla`.
+For production sites the `/installation` folder needs to be deleted after installation.
+
+See also [installJoomlaMultilingualSite](#installjoomlamultilingualsite).
+
+##### Usage
+
+```javascript
+cy.installJoomla(config)
```
-const installLanguage = (languageName) => {...};
-```
-**Variables**
-- `languageName`: \
- The name of the language to be installed.
-
----
+##### Arguments
-#### enablePlugin
+- **`config`** *(object)*: Configuration object containing sitename, name, username, password, email,
+ db_type, db_host, db_user, db_password, db_name and db_prefix.
-**Command**
+##### Example
+```javascript
+const config = {
+ sitename: "Sample Joomla Site",
+ name: "Joomla Administrator",
+ username: "admin",
+ password: "admin-password",
+ email: "sampleuser@example.com",
+ db_type: "MySQLi",
+ db_host: "localhost",
+ db_user: "joomla",
+ db_password: "joomla-db-user-password",
+ db_name: "sample_joomla",
+ db_prefix: "sjs_"
+}
+cy.installJoomla(config);
```
-Cypress.Commands.add('enablePlugin', enablePlugin);
-```
-**Function**
-```
-const enablePlugin = (pluginName) => {...};
-```
-**Variables**
+---
-- `pluginName`: \
- The name of the plugin to be enabled.
+#### `installJoomlaMultilingualSite`
----
+The command `installJoomlaMultilingualSite` first runs the [installJoomla](#installjoomla) command
+and continues the 'Joomla Installer' with installation of additional languages.
-#### setModulePosition
+The `/installation` folder is deleted after the installation.
+It is verified that the URL path '/installation' receives an error 404 – Not Found.
+This command can only run once.
-**Command**
+See also [installJoomla](#installjoomla).
-```
-Cypress.Commands.add('setModulePosition', setModulePosition);
-```
-**Function**
+##### Usage
+```javascript
+cy.installJoomlaMultilingualSite(config, languages)
```
-const setModulePosition = (module, position = 'position-7') => {...};
-```
-**Variables**
-- `module`: \
- The name of the module to be positioned.
-- `position`: \
- The position where the module should be placed (default is 'position-7').
+##### Arguments
+
+- **`config`** *(object)*: Configuration object containing sitename, name, username, password, email,
+ db_type, db_host, db_user, db_password, db_name and db_prefix.
+- **`languages`** *(string[], optional, default: ["French"])*: Array of additional languages to be installed.
+
+##### Example
+
+```javascript
+const config = {
+ sitename: "Sample Joomla Site",
+ name: "Joomla Administrator",
+ username: "admin",
+ password: "admin-password",
+ email: "sampleuser@example.com",
+ db_type: "MySQLi",
+ db_host: "localhost",
+ db_user: "joomla",
+ db_password: "joomla-db-user-password",
+ db_name: "sample_joomla",
+ db_prefix: "sjs_"
+}
+const languages = ["German", "Japanese", "Spanish", "Ukrainian"];
+cy.installJoomlaMultilingualSite(config, languages);
+```
---
-#### publishModule
+#### `cancelTour`
-**Command**
+Since Joomla version 5 there is a guided tour with the overlay 'Welcome to Joomla!'
+after first administrator login.
+The command `cancelTour` closes this guided tour overlay.
+The Joomla administrator must be logged in to do this.
+This is only possible once after installation and the first login.
+The timeout is extended to 40 seconds.
-```
-Cypress.Commands.add('publishModule', publishModule);
-```
-**Function**
+##### Usage
+```javascript
+cy.cancelTour()
```
-const publishModule = (module) => {...};
+
+##### Example
+
+```javascript
+cy.doAdministratorLogin("admin-user", "admin-user-password");
+cy.cancelTour();
```
-**Variables**
-- `module`: \
- The name of the module to be published.
-
---
-#### displayModuleOnAllPages
+#### `disableStatistics`
-**Command**
+To remove the system message container 'Enable Joomla Statistics?' from the backend home dashboard
+the command `disableStatistics` deactivates the plugin 'System - Joomla! Statistics'.
+This command can be executed multiple times without causing issues.
+The Joomla administrator must be logged in to do this.
-```
-Cypress.Commands.add('displayModuleOnAllPages', displayModuleOnAllPages);
-```
-**Function**
+##### Usage
+```javascript
+cy.disableStatistics()
```
-const displayModuleOnAllPages = (module) => {...};
-```
-**Variables**
-- `module`: \
- The name of the module to be displayed on all pages.
+##### Example
+
+```javascript
+cy.doAdministratorLogin("admin-user", "admin-user-password");
+cy.disableStatistics();
+```
---
-### Joomla Commands
+#### `setErrorReportingToDevelopment`
-#### installJoomla
+The command `setErrorReportingToDevelopment` sets 'Error Reporting' on the 'Server' tab in the Joomla 'Global Configuration'
+to 'Maximum'.
+This command can be executed multiple times without causing issues.
+The Joomla administrator must be logged in to do this.
-**Command**
+See also [checkForPhpNoticesOrWarnings](#checkforphpnoticesorwarnings).
-Installs Joomla via the user interface.
+##### Usage
+```javascript
+cy.setErrorReportingToDevelopment()
```
-Cypress.Commands.add('installJoomla', installJoomla);
-```
-**Function**
-Installs Joomla via the user interface.
+##### Example
-```
-const installJoomla = (config) => {...};
+```javascript
+cy.doAdministratorLogin("admin-user", "admin-user-password");
+cy.setErrorReportingToDevelopment();
```
-**Variables**
-
-- `config`: \
- Configuration object containing sitename, name, username, password, email, db_type, db_host, db_user, db_password, db_name, db_prefix.
-
---
-#### cancelTour
+### Extensions Commands
-**Command**
+#### `installExtensionFromFolder`
-Cancel a guided tour.
+The command `installExtensionFromFolder` installs an extension in Joomla from a folder on the server.
+It navigates to the Joomla extension installer page, selects 'Install from Folder',
+fills in the path to the folder and completes the installation.
+The Joomla administrator must be logged in to do this.
-```
-Cypress.Commands.add('cancelTour', cancelTour);
-```
+##### Usage
-**Function**
+```javascript
+cy.installExtensionFromFolder(path, type)
+```
-Cancels a tour in the Joomla interface.
+##### Arguments
-```
-const cancelTour = () => {...};
-```
+- **`path`** *(string, required)*: The path to the folder containing the extension.
+- **`type`** *(string, optional, default: 'Extension')*: The type of the extension.
-**Variables**
+##### Example
-None used.
+```javascript
+cy.doAdministratorLogin("admin-user", "admin-user-password");
+cy.installExtensionFromFolder("/joomla-module/src"); // as mounted in docker image
+```
---
-#### disableStatistics
+#### `installExtensionFromUrl`
-**Command**
+The command `installExtensionFromUrl` installs an extension in Joomla from the given URL.
+It navigates to the Joomla extension installer page, selects 'Install from URL',
+fills in URL and completes the installation.
+The Joomla administrator must be logged in to do this.
-Disable statistics.
+##### Usage
-```
-Cypress.Commands.add('disableStatistics', disableStatistics);
+```javascript
+cy.installExtensionFromUrl(url, type)
```
-**Function**
+##### Arguments
-Disables statistics in the Joomla interface.
+- **`url`** *(string, required)*: The URL where the extension can be downloaded.
+- **`type`** *(string, optional, default: 'Extension')*: The type of the extension.
-```
-const disableStatistics = () => {...};
-```
+##### Example
-**Variables**
-
-None used.
+```javascript
+cy.doAdministratorLogin("admin-user", "admin-user-password");
+cy.installExtensionFromUrl("https://server.org/download/joomla-module.zip");
+```
---
-#### setErrorReportingToDevelopment
+#### `installExtensionFromFileUpload`
-**Command**
+The command `installExtensionFromFileUpload` installs an extension in Joomla from the specified package file
+in the Cypress Test Runner (web browser) environment.
+It navigates to the Joomla extension installer page, selects 'Upload Package File',
+fills the path to the file and completes the installation.
+The Joomla administrator must be logged in to do this.
+It is based on the custom command `attachFile` from the `cypress-file-upload` module.
-Sets error reporting to development mode.
+##### Usage
+```javascript
+cy.installExtensionFromFileUpload(file, type)
```
-Cypress.Commands.add('setErrorReportingToDevelopment', setErrorReportingToDevelopment);
-```
-
-**Function**
-Sets error reporting to development mode in the Joomla configuration.
+##### Arguments
-```
-const setErrorReportingToDevelopment = () => {...};
-```
+- **`file`** *(string, required)*: The path to the package file.
+- **`type`** *(string, optional, default: 'Extension')*: The type of the extension.
-**Variables**
+##### Example
-None used.
+```javascript
+cy.doAdministratorLogin("admin-user", "admin-user-password");
+cy.installExtensionFromFileUpload("manual-examples.zip");
+```
---
-#### installJoomlaMultilingualSite
+#### `uninstallExtension`
-**Command**
+The command `uninstallExtension` removed an installed extension from Joomla.
+It ensures that there are no warning messages after deletion and
+checks afterwards that the extension no longer exists.
+The Joomla administrator must be logged in to do this.
-Installs Joomla as a multi-language site.
+##### Usage
-```
-Cypress.Commands.add('installJoomlaMultilingualSite', installJoomlaMultilingualSite);
+```javascript
+cy.uninstallExtension(extensionName)
```
-**Function**
+##### Arguments
-Installs Joomla as a multi-language site using provided configurations and languages.
+- **`extensionName`** *(string)*: The name of the extension.
-```
-const installJoomlaMultilingualSite = (config, languages = []) => {...};
+##### Example
+
+```javascript
+cy.doAdministratorLogin("admin-user", "admin-user-password");
+cy.uninstallExtension("Joomla module tutorial");
```
-**Variables**
+---
-- `config`: \
-Configuration object containing sitename, name, username, password, email, db_type, db_host, db_user, db_password, db_name, db_prefix.
-- `languages`: \
-Array of languages to be installed (default is an empty array).
+#### `installLanguage`
-### Support Commands
+The command `installLanguage` installs a language pack in Joomla.
+The Joomla administrator must be logged in to do this.
+If the language pack is already installed, a reinstall is executed.
-#### clickToolbarButton
+##### Usage
-**Command**
+```javascript
+cy.installLanguage(languageName)
+```
-Clicks on a button in the toolbar.
+##### Arguments
+- **`languageName`** *(string)*: Language name or language tag.
+
+##### Example
+
+```javascript
+cy.doAdministratorLogin("admin-user", "admin-user-password");
+// Install German for Switzerland with language tag
+cy.installLanguage("de-CH");
+// or install with language name
+// cy.installLanguage("German, Switzerland");
```
-Cypress.Commands.add('clickToolbarButton', clickToolbarButton);
-```
-**Function**
+---
+
+#### `enablePlugin`
-Clicks on a button in the Joomla toolbar based on the button name and optional subselector.
+The command `enablePlugin` activates a Joomla plugin so that is becomes operational.
+If the specified plugin is already activated, the command will fail.
+The Joomla administrator must be logged in to do this.
-```
-const clickToolbarButton = (button, subselector = null) => {...};
+##### Usage
+
+```javascript
+cy.enablePlugin(pluginName)
```
-**Variables**
+##### Arguments
-- `button`: \
- Name of the button to be clicked.
-- `subselector`: \
- Optional subselector for more specific targeting within the button (default is null).
+- **`pluginName`** *(string)*: The plugin name.
+
+##### Example
+
+```javascript
+cy.doAdministratorLogin("admin-user", "admin-user-password");
+cy.enablePlugin("Authentication - LDAP");
+```
---
-#### checkForPhpNoticesOrWarnings
+#### `setModulePosition`
-**Command**
+The command `setModulePosition` sets a module display position within a Joomla template.
+The Joomla administrator must be logged in to do this.
-Checks for PHP notices and warnings in the current page.
+##### Usage
+```javascript
+cy.setModulePosition(module, position)
```
-Cypress.Commands.add('checkForPhpNoticesOrWarnings', checkForPhpNoticesOrWarnings);
-```
-
-**Function**
-Checks the HTML source of the current page for PHP notices and warnings.
+##### Arguments
-```
-const checkForPhpNoticesOrWarnings = () => {...};
-```
+- **`module`** *(string)*: The module name.
+- **`position`** *(string, optional, default: 'position-7')*: The display position.
-**Variables**
+##### Example
-None used.
+```javascript
+cy.doAdministratorLogin("admin-user", "admin-user-password");
+cy.setModulePosition("module-name", "sidebar-right");
+```
---
-#### checkForSystemMessage
+#### `publishModule`
-**Command**
+The command `publishModule` makes the module active and visible on the Joomla website.
+It navigates to the Joomla modules list, selects the module and sets the status to Published.
+It does not matter whether the module has already been published,
+as the module found is initially set to the status Unpublished.
+The Joomla administrator must be logged in to do this.
-Checks for a system message containing specific text.
+##### Usage
-```
-Cypress.Commands.add('checkForSystemMessage', checkForSystemMessage);
+```javascript
+cy.publishModule(module)
```
-**Function**
+##### Arguments
-Checks if a system message containing specified text is visible.
+- **`module`** *(string)*: The module name.
-```
-const checkForSystemMessage = (contain) => {...};
-```
+##### Example
-**Variables**
+```javascript
+cy.doAdministratorLogin("admin-user", "admin-user-password");
+cy.publishModule("Breadcrumbs");
+```
-- `contain`: \
- Text content to check within the system message.
-
---
-#### searchForItem
+#### `displayModuleOnAllPages`
-**Command**
+The command `displayModuleOnAllPages` sets the menu assignment for the specified module for all pages in Joomla.
+The Joomla administrator must be logged in to do this.
-Searches for an item using the Joomla interface.
+##### Usage
-```
-Cypress.Commands.add('searchForItem', searchForItem);
+```javascript
+cy.displayModuleOnAllPages(module)
```
-**Function**
+##### Arguments
-Initiates a search for an item within Joomla based on the provided name.
+- **`module`** *(string)*: The module name.
-```
-const searchForItem = (name = null) => {...};
-```
+##### Example
-**Variables**
+```javascript
+cy.doAdministratorLogin("admin-user", "admin-user-password");
+cy.displayModuleOnAllPages("Login Form");
+```
-- `name`: \
- Optional name of the item to search for (default is null).
-
---
-#### setFilter
+### Support Commands
-**Command**
+#### `clickToolbarButton`
-Sets a filter on the list view in Joomla.
+The command `clickToolbarButton` clicks on a Joomla backend button by using an internal mapping table.
+For example the button 'Enable' is mapped to click on CSS selector `#toolbar-publish button'.
+For the button 'transition' it is possible to give an additional subselector string.
-```
-Cypress.Commands.add('setFilter', setFilter);
+##### Usage
+
+```javascript
+cy.clickToolbarButton(button, subselector)
```
-**Function**
+##### Arguments
-Sets a filter on the Joomla list view based on the provided filter name and value.
+- **`button`** *(string)*: Name of the button to be clicked (case insensitive).
+- **`subselector`** *(string, optional, default: null)*: Optional subselector for more specific targeting within the button.
-```
-const setFilter = (name, value) => {...};
-```
+##### Example
-**Variables**
+```javascript
+cy.clickToolbarButton('Save & Close');
+```
-- `name`: \
- Name of the filter to set.
-- `value`: \
- Value to set for the filter.
-
---
-#### checkAllResults
+#### `checkForPhpNoticesOrWarnings`
-**Command**
+The command `checkForPhpNoticesOrWarnings` checks for PHP notices and warnings in the HTML page source.
+It looks for keywords such as 'Deprecated' in bold followed by a colon.
+If such a styled keyword is found, the Cypress test fails with the PHP problem message.
+Looking for:
+* **Warning**:
+* **Deprecated**:
+* **Notice**:
+* **Strict standards**:
-Checks all results in the Joomla list view.
+To make the PHP notes and warnings visible,
+the command [setErrorReportingToDevelopment](#seterrorreportingrodevelopment)
+needs to be executed once beforehand.
-```
-Cypress.Commands.add('checkAllResults', checkAllResults);
-```
+:point_right: This command could be used in Cypress `afterEach()` to run after each test block.
-**Function**
+See also [setErrorReportingToDevelopment](#seterrorreportingtodevelopment).
-Selects all results by checking the 'check all' checkbox in the Joomla list view.
+##### Usage
-```
-const checkAllResults = () => {...};
+```javascript
+cy.checkForPhpNoticesOrWarnings()
```
-**Variables**
+##### Example
-None used.
+```javascript
+cy.checkForPhpNoticesOrWarnings();
+```
---
-#### createMenuItem
+#### `checkForSystemMessage`
-**Command**
+The command `checkForSystemMessage` checks that a Joomla system message exists,
+is visible and contains a specific text.
-Creates a new menu item in Joomla.
+##### Usage
-```
-Cypress.Commands.add('createMenuItem', createMenuItem);
+```javascript
+cy.checkForSystemMessage(contain)
```
-**Function**
+##### Arguments
-Creates a new menu item in Joomla with specified parameters.
+- **`contain`** *(string)*: The substring that must be included in the system message.
-```
-const createMenuItem = (menuTitle, menuCategory, menuItem, menu = 'Main Menu', language = 'All') => {...};
-```
+##### Example
-**Variables**
+This command is used, for example, in the command [installExtensionFromFolder](#installextensionfromfolder)
+to check if the installation of the extension was successful
+by checking if there is a system message containing "was successful".
-- `menuTitle`: \
- Title of the new menu item.
-- `menuCategory`: \
- Category of the menu item.
-- `menuItem`: \
- Type of the menu item.
-- `menu`: \
- Menu where the item will be created (default is 'Main Menu').
-- `language`: \
- Language for the menu item (default is 'All').
+```javascript
+cy.checkForSystemMessage('was successful');
+```
---
-#### createCategory
+#### `searchForItem`
-**Command**
+The command `searchForItem` searches for a specific name in a Joomla list and
+clicks on the checkbox at the beginning of the corresponding list entry.
+As a prerequisite, the list must be open.
+The search field is used to avoid paging.
+The list entry being searched for is selected as the result.
-Creates a new category in Joomla.
+##### Usage
-```
-Cypress.Commands.add('createCategory', createCategory);
+```javascript
+cy.searchForItem(name)
```
-**Function**
+##### Arguments
-Creates a new category in Joomla with specified title and extension.
+- **`name`** *(string, optional, default: null)*: Name of the item to search for.
-```
-const createCategory = (title, extension = 'com_content') => {...};
-```
+##### Example
-**Variables**
+This command is used, for example, in the [enablePlugin](#enableplugin) command
+to select the plugin to be enabled.
-- `title`: \
- Title of the new category.
-- `extension`: \
- Extension associated with the category (default is 'com_content').
+```javascript
+cy.doAdministratorLogin("admin-user", "admin-user-password");
+cy.visit('/administrator/index.php?option=com_plugins');
+cy.searchForItem(pluginName);
+```
---
-#### selectOptionInFancySelect
+#### `setFilter`
-**Command**
+The command `setFilter` sets a filter on the list view in Joomla.
-Selects an option from a fancy select field in Joomla.
+##### Usage
-```
-Cypress.Commands.add('selectOptionInFancySelect', selectOptionInFancySelect);
+```javascript
+cy.setFilter(name, value)
```
-**Function**
+##### Arguments
-Selects an option from a fancy select field identified by selectId.
+- **`name`** *(string)*: Name of the filter to set.
+- **`value`** *(string)*: Value to set for the filter.
-```
-const selectOptionInFancySelect = (selectId, option) => {...};
-```
+##### Example
-**Variables**
+In the following example, the list of user entries is filtered to "State: Activated":
+
+```javascript
+// Using 'username' and 'password' from Cypress.env()
+cy.doAdministratorLogin()
+ // Open user list
+ .visit('/administrator/index.php?option=com_users')
+ // Only enabled user entries
+ .setFilter('state', 'Enabled');
+```
-- `selectId`: \
- ID of the fancy select field.
-- `option`: \
- Option to be selected from the fancy select field.
-
---
-#### toggleSwitch
+#### `checkAllResults`
-**Command**
+Joomla list views are page by page.
+The command `checkAllResults` displays all list entries in one page by marking 'All' entries in the Joomla list view.
+As a prerequisite, the list must be open.
-Toggles a switch field in Joomla.
+##### Usage
-```
-Cypress.Commands.add('toggleSwitch', toggleSwitch);
+```javascript
+cy.checkAllResults()
```
-**Function**
+##### Example
-Toggles a switch field identified by fieldName to the specified valueName.
-
-```
-const toggleSwitch = (fieldName, valueName) => {...};
+```javascript
+// Show all extensions in one single page:
+cy.doAdministratorLogin
+ .visit('/administrator/index.php?option=com_installer&view=manage')
+ .checkAllResults();
```
-**Variables**
-
-- `fieldName`: \
- Name of the switch field to toggle.
-- `valueName`: \
- Value to toggle the switch field to.
-
---
-### User Commands
+#### `createMenuItem`
-#### doAdministratorLogin
+The command `createMenuItem` creates a new menu item in Joomla.
-**Command**
+The Language parameter is only used if the Joomla website is set up multingual.
+This means that at least one additional language must be installed and the
+"System - Language Filter" plugin must be activated.
+Otherwise, the language selection is ignored.
+For the `language` parameter the language name (e.g. "Japanese (Japan)") or the language tag (e.g. "ja-JP") can be used.
+Default is "All".
-Initiates administrator login process.
+##### Usage
-```
-Cypress.Commands.add('doAdministratorLogin', doAdministratorLogin);
+```javascript
+cy.createMenuItem(menuTitle, menuCategory, menuItem, menu, language)
```
-**Function**
+##### Arguments
-Performs administrator login with provided credentials or defaults to environment
-variables.
+- **`menuTitle`** *(string)*: The title of the new menu item.
+- **`menuCategory`** *(string)*: The category of the menu item.
+- **`menuItem`** *(string)*: The type of the menu item.
+- **`menu`** *(string, optional, default: 'Main Menu')*: The menu where the item will be created.
+- **`language`** *(string, optional, default: 'All')*: The language for the menu item.
-```
-const doAdministratorLogin = (user, password, useSnapshot = true) => {...};
-```
-
-**Variables**
+##### Example
-- `user`: \
-Username for login. Defaults to Cypress environment variable if not provided.
-- `password`: \
-Password for login. Defaults to Cypress environment variable if not provided.
-- `useSnapshot`: \
-Boolean flag to determine if the session should be cached across specs (default is true).
+The following code creates a menu entry 'Spotlight Story' for featured articles as a Japanese menu entry,
+for the Japanese language and in the Japanese menu.
+```javascript
+// Create Japanese menu item 'Spotlight Stories'
+cy.doAdministratorLogin("admin-user", "admin-user-password");
+ .createMenuItem('スポットライト・ストーリー', 'Articles', 'Featured Articles', 'Menu 日本語', 'ja-JP');
+```
---
-#### doAdministratorLogout
+#### `createCategory`
-**Command**
+The command `createCategory`creates a new category in Joomla with the specified title.
+Categories can be created to organise:
+* Content articles – extension 'com_content',
+* News feeds – extension 'com_newsfeeds',
+* Banners – extension 'com_banners' or
+* Contacts – extension 'com_contact'.
-Initiates administrator logout process.
+If the category with the specified title and extension already exists, the command will fail.
-```
-Cypress.Commands.add('doAdministratorLogout', doAdministratorLogout);
-```
+##### Usage
-**Function**
+```javascript
+cy.createCategory(title, extension)
+```
-Logs out from the Joomla administrator interface.
+##### Arguments
-```
-const doAdministratorLogout = () => {...};
-```
+- **`title`** *(string)*: The title of the new category.
+- **`extension`** *(string, optional, default: 'com_content')*: The content type of the category.
-**Variables**
+##### Example
-None used.
+```javascript
+// Create Monday banners category
+cy.doAdministratorLogin()
+ .createCategory("Monday Banners", "com_banners");
+```
---
-#### doFrontendLogin
+#### `selectOptionInFancySelect`
-**Command**
+The command `selectOptionInFancySelect` selects an option from a fancy select field in Joomla.
-Initiates frontend login process.
+##### Usage
-```
-Cypress.Commands.add('doFrontendLogin', doFrontendLogin);
+```javascript
+cy.selectOptionInFancySelect(selectId, option)
```
-**Function**
+##### Arguments
-Logs into the Joomla frontend using provided credentials or environment variables.
+- **`selectId`** *(string)*: The CSS ID of the fancy select field.
+- **`option`** *(string)*: The option to be selected from the fancy select field.
-```
-const doFrontendLogin = (user, password, useSnapshot = true) => {...};
-```
-
-**Variables**
+##### Example
-- `user`: \
-Username for login. Defaults to Cypress environment variable if not provided.
-- `password`: \
-Password for login. Defaults to Cypress environment variable if not provided.
-- `useSnapshot`: \
-Boolean flag to determine if the session should be cached across specs (default is true).
+
+```javascript
+cy.selectOptionInFancySelect("#jform_countries", "Germany");
+```
---
-#### doFrontendLogout
+#### `toggleSwitch`
-**Command**
+The command `toggleSwitch` toggles a switch field in Joomla identified by fieldName to the specified value name.
-Initiates frontend logout process.
+##### Usage
-```
-Cypress.Commands.add('doFrontendLogout', doFrontendLogout);
+```javascript
+cy.toggleSwitch(fieldName, valueName)
```
-**Function**
+##### Arguments
-Logs out from the Joomla frontend.
+- **`fieldName`** *(string)*: The name of the switch field to toggle.
+- **`valueName`** *(string)*: The value to toggle the switch field to.
-```
-const doFrontendLogout = () => {...};
-```
-
-**Variables**
+##### Example
-None used.
+
+```javascript
+cy.toggleSwitch("Published", "Yes");
+```
---
-#### createUser
+### Common Commands
-**Command**
+#### `iframe`
-Creates a new user in the Joomla administrator interface.
+The command `iframe` works with iframe elements.
+It waits for the iframe to be fully loaded and resolves with the iframe's body content,
+allowing to interact with elements inside the iframe seamlessly.
-```
-Cypress.Commands.add('createUser', createUser);
-```
+##### Usage
-**Function**
-
-Creates a new user with specified details.
-
-```
-const createUser = (name, username, password, email, userGroup = 'Super Users') => {...};
+```javascript
+cy.get('iframe').iframe()
```
-**Variables**
+##### Example
-- `name`: \
-Name of the user.
-- `username`: \
-Username for the new user.
-- `password`: \
-Password for the new user.
-- `email`: \
-Email address for the new user.
-- `userGroup`: \
-User group to assign the new user (default is 'Super Users').
+```javascript
+cy.get('iframe').iframe().then($body => {
+ // You can now interact with the iframe's body as a Cypress element
+ cy.wrap($body).find('selector-within-iframe').click();
+});
+```
---
-## Usage Samples
-You can see the usage by sample:
-* [joomla-cms](https://github.com/joomla/joomla-cms//blob/HEAD/tests/System) see `tests/System` – The Joomla System Tests, using e.g.
- `cy.installJoomla`, `cy.doFrontendLogin()` or `cy.clickToolbarButton`
-* [manual-examples](https://github.com/joomla/manual-examples) - Testing the Joomla module tutorial sample
- from the development manual, using e.g. `cy.doAdministratorLogin`, `cy.setModulePosition` or `cy.installExtensionFromFileUpload`
+## Usage Examples from the Field
+You can see the practical use in various projects:
+* [joomla-cms](https://github.com/joomla/joomla-cms//blob/HEAD/tests/System) see folder `tests/System` –
+ The Joomla System Tests, using e.g.
+ `cy.installJoomla`, `cy.doFrontendLogin` or `cy.clickToolbarButton`
+* [manual-examples](https://github.com/joomla/manual-examples) see folder `tests` - Testing the Joomla module
+ tutorial sample from the development manual, using e.g. `cy.doAdministratorLogin`, `cy.setModulePosition` or
+ `cy.installExtensionFromFileUpload`
* [quote_joomla](https://github.com/muhme/quote_joomla/tree/main/test) – Installation of a Joomla module, using e.g.
`cy.installJoomlaMultilingualSite`, `cy.installExtensionFromFolder` or `cy.publishModule`
+
+
+[version-badge]: https://img.shields.io/npm/v/joomla-cypress
+[package]: https://www.npmjs.com/package/joomla-cypress
+