@jahia/cypress ====================== ## Commands [`.apollo()`](./src/support/apollo/apollo.md) [`.apolloClient()`](./src/support/apollo/apolloClient.md) [`.runProvisioningScript()`](./src/support/provisioning/runProvisioningScript.md) [`.executeGroovy()`](./src/support/provisioning/executeGroovy.md) [`.login()`](./src/support/login.md) [`.logout()`](./src/support/logout.md) [`.repeatUntil()`](./src/support/repeatUntil.md) [`it.since()`](#version-gated-tests) [`describe.since()`](#version-gated-tests) ## Page / component objects In Page Object Model, a set of object is provided to handle known and reused web elements. These page objects provide method to handle interactions with these web elements. Web elements can be simple HTML elements, more complex UI components or full pages. This framework does not come with predefined page objects, as they should be provided by the modules which define them. TODO: Moonstone page object are defined here, but could be moved to moonstone ### Implementation #### Components Page object representing a component extends `baseComponent`. Creating a page object will enqueue a command looking for the corresponding DOM element. An alias to this element will be stored in the object. Page object can provide accessors to other page object, and methods that will enqueue other cypress commands and assertions. [`moonstone`](./src/page-object/moonstone) #### Pages Page object representing an HTML page extends `basePage`. They can provide a static visit() method to open the page, and returns an instance of the page object. Constructor can initialize components that are present in the page. This will assert that these components are present, and make them available for the tests. [`jcontent.md`](./src/page-object/jcontent/jcontent.ts) ### Sample usage ```typescript const primaryNav = new PrimaryNav() // Look for primary nav elements primaryNav.listItems().expect('...') // Check primary nav content primaryNav.select('jcontent') // Select the corresponding item and click on it ``` ```typescript let jcontent = JContent.visit("digitall", "en", "pages"); jcontent.select('content-folders') const m = jcontent.getTable().getRow(1).contextMenu() m.select('edit') ``` ## Configure Add `@jahia/cypress` to your project. Add cypress commands and support : in support/index.js, adds : ```js require('@jahia/cypress/dist/support/registerSupport').registerSupport() ``` Add typings in your tsconfig.json : ```json { "types": [ "@jahia/cypress" ] } ``` This project provides a plugin for settings environment variable based on system env ( `JAHIA_URL` and `SUPER_USER_PASSWORD` ) Set up your plugins: in `plugins/index.js`, calls the module in `@jahia/cypress/dist/plugins/registerPlugins` : ```js module.exports = (on, config) => { require('@jahia/cypress/dist/plugins/registerPlugins').registerPlugins(on, config) // register other plugins return config; }; ``` ## Version-gated tests After enabling `modSince` via `registerSupport`, you can gate tests and suites by Jahia version with: - `it.since(requiredVersion, title, testFn)` - `describe.since(requiredVersion, title, suiteFn)` Modifiers are supported as well: - `it.only.since(...)`, `describe.only.since(...)` - `it.skip.since(...)`, `describe.skip.since(...)` `it.since(...)` and `describe.since(...)` run only when current Jahia version is greater than or equal to `requiredVersion`; otherwise they are skipped. `it.skip.since(...)` and `describe.skip.since(...)` are always skipped (same behavior as Cypress `skip`, with a version argument for consistency). Jahia version is fetched in a root `before()` hook and stored in environment variable `CYPRESS_JAHIA_VERSION`. ```typescript it.since('8.2.0', 'shows the new dashboard widget', () => { // test body }); describe.since('8.2.0', 'dashboard suite available since 8.2', () => { it('renders the widget list', () => { // suite test body }); }); // `only` modifiers are also supported it.only.since('8.2.0', 'focused version-gated test', () => { // test body }); describe.only.since('8.2.0', 'focused version-gated suite', () => { it('runs suite tests', () => { // suite test body }); }); // `skip` modifiers are also supported it.skip.since('8.2.0', 'always skipped version-gated test', () => { // skipped }); describe.skip.since('8.2.0', 'always skipped version-gated suite', () => { it('is skipped', () => { // skipped }); }); ``` ## Internal Auxiliary Libraries ### Extended Logger Module Helper utility designed to enhance Cypress test logging capabilities by providing structured log levels and decorating log messages with appropriate severity indicators. It enables developers to create more organized and filterable test output by categorizing log messages into different levels. Read more [here](./docs/extended-logger.md). ### JavaScript Errors Logger Comprehensive monitoring and reporting module for JavaScript errors and warnings in Cypress tests. It provides automated detection, collection, and reporting of console errors and warnings that occur during test execution, helping maintain code quality and identify issues early in the development process. Read more [here](./docs/js-errors-logger.md). ### jFaker - Fake Data Generation Module Flexible fake data generation utility for Cypress testing that combines the power of Faker.js with security-focused injection payload generation. It provides a unified API to generate both realistic test data and security testing payloads (XSS, SQL injection, etc.) through a dynamic proxy-based interface. Read more [here](./docs/jfaker.md). ### Global Vars Generic `getGlobalVar`/`setGlobalVar` key/value store, backed by `cy.task()`, for sharing state across every spec file in a single Cypress run — something `Cypress.env()` can't do, since it resets between spec files. Read more [here](./docs/global-vars.md). ### SMTP Server Support Configuration guide for setting up mail server support (`mailpit`) so your tests can receive Jahia mails and notifications. Read more [here](./docs/using-smtp-server.md). ## Open-Source This is an Open-Source codebase, you can find more details about Open-Source @ Jahia [in this repository](https://github.com/Jahia/open-source) ## How to release Releases are now automated using [Chachalog](https://github.com/GauBen/chachalog). To create a new release, merge the `chore: release` PR from `github-actions`: the package is then published to NPM and tagged `@jahia/cypress@X.Y.Z` automatically.