{"id":21430161,"url":"https://github.com/cuba-platform/masquerade","last_synced_at":"2025-07-14T11:31:16.619Z","repository":{"id":27929125,"uuid":"115034718","full_name":"cuba-platform/masquerade","owner":"cuba-platform","description":"CUBA Platform UI Testing Library","archived":false,"fork":false,"pushed_at":"2022-04-26T09:40:37.000Z","size":428,"stargazers_count":29,"open_issues_count":36,"forks_count":7,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-04-15T02:04:36.045Z","etag":null,"topics":["cuba-platform","selenide","ui-testing"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cuba-platform.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-12-21T18:22:01.000Z","updated_at":"2023-08-19T11:24:43.000Z","dependencies_parsed_at":"2022-08-07T13:01:20.443Z","dependency_job_id":null,"html_url":"https://github.com/cuba-platform/masquerade","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuba-platform%2Fmasquerade","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuba-platform%2Fmasquerade/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuba-platform%2Fmasquerade/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuba-platform%2Fmasquerade/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cuba-platform","download_url":"https://codeload.github.com/cuba-platform/masquerade/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225972030,"owners_count":17553574,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cuba-platform","selenide","ui-testing"],"created_at":"2024-11-22T22:21:06.179Z","updated_at":"2024-11-22T22:21:06.867Z","avatar_url":"https://github.com/cuba-platform.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"masquerade\n==========\n\nCuba Platform UI testing library.\n\n\u003ca href=\"http://www.apache.org/licenses/LICENSE-2.0\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat\" alt=\"license\" title=\"\"\u003e\u003c/a\u003e\n\u003ca href='https://bintray.com/cuba-platform/main/masquerade/2.0.1/link'\u003e\u003cimg src='https://api.bintray.com/packages/cuba-platform/main/masquerade/images/download.svg?version=2.0.1'\u003e\u003c/a\u003e\n\u003ca href=\"https://travis-ci.org/cuba-platform/masquerade\"\u003e\u003cimg src=\"https://travis-ci.org/cuba-platform/masquerade.svg?branch=master\" alt=\"Build Status\" title=\"\"\u003e\u003c/a\u003e\n\n## Overview\n\nThe library provides an ability to create UI tests for CUBA-based applications. \nIt can help you to write better tests.\n\nIt is based on:\n\n* Java\n* Selenide\n* Selenium\n\n# Getting started\n    \n## Creating test project \n    \nCreate a simple Java project in IntelliJ IDEA. The project should have the \nfollowing structure:\n\n```\n+ src\n  + main \n    + java\n  + test\n    + java\n      + com/company/demo\n+ build.gradle\n+ settings.gradle  \n```\n\nHere’s the complete `build.gradle` file:\n\n```groovy\napply plugin: 'java'\n\ngroup = 'com.company.demo'\nversion = '0.1'\n\nsourceCompatibility = 1.8\n\nrepositories {\n    mavenCentral()    \n    maven {\n        url \"https://dl.bintray.com/cuba-platform/main\"\n    }    \n}\n\ndependencies {\n    testCompile('junit:junit:4.12')\n    \n     //the library for the UI testing\n    testCompile('com.haulmont.masquerade:masquerade-web:\u003ccheck the latest version\u003e')\n    \n    //the library provides an ability to access web-services, JMX and etc.\n    testCompile('com.haulmont.masquerade:masquerade-connector:\u003ccheck the latest version\u003e')\n    \n    // enable logging\n    testCompile('org.slf4j:slf4j-simple:1.7.25')\n}\n```\n\nFind the latest version number here: https://bintray.com/cuba-platform/main/masquerade\n\n## Creating a test\n\nIn the `src/test/java` folder create a new package in the `com.company.demo` and name it `composite`. Create \na new Java class in this package and name it `LoginWindow`. This class \nshould be inherited from the `Composite\\\u003cT\u003e` where `T` is the name of your \nclass. This class will be used as a helper class, usually it declares UI \ncomponents of an application screen / frame / panel that is shown in a web page. \nAlso, all test methods can be declared here.\n \nAll class attributes should be marked with the ```@Wire``` annotation. \nThis annotation has optional `path` element which allows userService to define \nthe path to the component using the `cuba-id` parameter. If the component does \nnot have the `cuba-id` parameter, you can use the ```@FindBy``` annotation \ninstead. This annotation has a list of optional parameters, like `name`, \n`className`, `id` and so on, which helps to identify the component.\n\nThe type of the attribute in the class corresponds to the type of the screen \ncomponent. If the component has a type which is not defined in the library, use \nthe `Untyped` type. \n\nThe name of the attribute corresponds to the `cuba-id` attribute of a DOM \nelement that corresponds to the UI component. \n\n```java\nimport com.haulmont.masquerade.Wire;\nimport com.haulmont.masquerade.base.Composite;\nimport com.haulmont.masquerade.components.Button;\nimport com.haulmont.masquerade.components.CheckBox;\nimport com.haulmont.masquerade.components.Label;\nimport com.haulmont.masquerade.components.LookupField;\nimport com.haulmont.masquerade.components.PasswordField;\nimport com.haulmont.masquerade.components.TextField;\nimport org.openqa.selenium.support.FindBy;\n\npublic class LoginWindow extends Composite\u003cLoginWindow\u003e {\n\n    @Wire\n    public TextField loginField;\n\n    @Wire\n    public PasswordField passwordField;\n\n    @Wire(path = \"rememberMeCheckBox\")\n    public CheckBox rememberMeCheckBox;\n\n    @Wire(path = {\"loginFormLayout\", \"loginButton\"})\n    public Button loginSubmitButton;\n\n    @Wire\n    public LookupField localesSelect;\n\n    @Wire\n    public Label welcomeLabel;\n\n    @FindBy(className = \"c-login-caption\")\n    public Label welcomeLabelTest;\n}\n``` \n\nCreate a Java class in the `com.company.demo` package in the `src/test/java` folder. Name it `LoginWindowTest`. \n\nCreate a new method and add ```@Test``` annotation to it. The ```@Test``` \nannotation tells JUnit that the public void method can be run as a test case. \n \nYou can use all JUnit annotations to improve the tests. Also it is possible to \nuse a set of assertion methods provided by JUnit.\n \n```java\nimport com.company.demo.composite.LoginWindow;\nimport com.haulmont.masquerade.components.Untyped;\nimport org.junit.Test;\n\nimport static com.codeborne.selenide.Selenide.close;\nimport static com.codeborne.selenide.Selenide.open;\nimport static com.haulmont.masquerade.Components.$c;\nimport static com.haulmont.masquerade.Components.wire;\nimport static com.haulmont.masquerade.Conditions.*;\n\npublic class LoginWindowTest {\n\n    @Test\n    public void loginTest() {\n        // open URL of an application\n        open(\"http://localhost:8080/app\");\n\n        // obtain UI object\n        LoginWindow loginWindow = $c(LoginWindow.class);\n\n        loginWindow.loginField\n                .shouldBe(EDITABLE)\n                .shouldBe(ENABLED);\n\n        // setting values\n        loginWindow.loginField.setValue(\"admin\");\n        loginWindow.passwordField.setValue(\"admin\");\n        loginWindow.rememberMeCheckBox.setChecked(true);\n\n        // fluent asserts\n        loginWindow.welcomeLabel\n                .shouldBe(VISIBLE);\n\n        loginWindow.loginSubmitButton\n                .shouldBe(VISIBLE)\n                .shouldBe(ENABLED)\n                .shouldHave(caption(\"Submit\"));\n\n        loginWindow.rememberMeCheckBox\n                .shouldBe(VISIBLE)\n                .shouldBe(CHECKED);\n\n        // get values from Component\n        String caption = loginWindow.loginSubmitButton.getCaption();\n        boolean enabled = loginWindow.loginSubmitButton.is(ENABLED);\n\n        Untyped loginFormLayout = wire(Untyped.class, \"loginFormLayout\");\n        loginFormLayout.shouldBe(VISIBLE);\n\n        loginWindow.loginSubmitButton.click();\n        \n        close();\n    }\n}\n``` \n\nThe `open()` method is a standard Selenide method. It opens a browser window \nwith the given URL. The second line creates an instance of the masquerade \nComponent and binds it to the UI component (LoginWindow) on the screen including \nall the annotated fields inside of the LoginWindow class. After that, you can \naccess the screen components as class attributes. You can check the attributes \nvisibility, get captions, set values, click the buttons and so on.\n\n# Tips \u0026 Tricks\n\nHere are some useful tips on how to work with the library.\n\n## How to work with elements\n\nThe library has a special method  ```$c``` to define any element on the screen. \nThis method has three implementations:\n\n* The first implementation gets the element by its class:\n\n    ```$c(Class\u003cT\u003e clazz)```\n* The second implementation gets the element by its class and the path:\n\n    ```$c(Class\u003cT\u003e clazz, String... path)```\n* The third implementation gets the element by its class and _by_ selector:\n\n    ```$c(Class\u003cT\u003e clazz, By by)```\n    \nFor example, we can click the button on the screen: \n\n```java\nimport static com.haulmont.masquerade.Components.$c;\n\n$c(Button, 'logoutButton').click();\n```\n\n## How to check the state of an element\n\nSelenide allows you to check some conditions.\n\nTo check if the element is enabled, visible or checked, use the `shouldBe` \nelement. For example:\n\n```java\nloginButton\n   .shouldBe(VISIBLE)\n   .shouldBe(ENABLED);\n```\n\nTo check if the element has some properties, use the `shouldHave` element. For example:\n\n```java\nwelcomeLabel.shouldHave(Conditions.value('Welcome to CUBA!'));\n```    \n\n## How to work with the Selenide elements\n    \nIf the component does not have the `cuba-id` parameter, you can use the \n```@FindBy``` annotation. This annotation has a list of optional parameters, \nlike `name`, `className`, `id` and so on, which helps to identify the component.\n\n```java\n@FindBy(className = \"c-login-caption\")\npublic Label welcomeLabelTest;\n```    \n\nAlso, using this annotation, you can define `SelenideElement` type for the attribute \ninstead of the types provides by masquerade. After that, you can use all test \nmethods provided by Selenide. The name of the attribute can be any.\n\n```java\nimport com.codeborne.selenide.SelenideElement;\n\n@FindBy(className = \"c-login-caption\")\npublic SelenideElement welcomeLabelTest;\n```   \n\nAnother way to define the `SelenideElement` type attribute is using the \n```@Wire``` annotation. You can write the `SelenideElement` type instead of \nmasquerade types, but the name of the attribute should correspond to the \n`cuba-id` attribute of a DOM element that corresponds to the UI component.\n\n```java\n@Wire\npublic SelenideElement loginField;\n```    \n\nThe third way to work with the Selenide elements is to use ```getDelegate()``` \nmethod. This method returns the `SelenideElement` type component. After that, you \ncan use all test methods provided by Selenide.\n\n```java\nloginWindow.getDelegate().exists();\n```    \n\n## Useful tips for the Groovy tests\n\nYou can use any JVM language with the library including Groovy / Scala / Kotlin. \nThere are some useful tips for those who use Groovy to write the tests. \n\n* .with() method.\n\nGroovy closures have a delegate associated with them. The delegate can respond \nto method calls which happen inside of the closure. It enables you to use \nmethods/properties within a `with {}` closure without having to repeat the \nobject name each time.\n\n```groovy\nloginWindow.with {\n    loginField.value = 'testUser'\n    passwordField.value = '1'\n    rememberMeCheckBox.checked = true\n\n    commit()\n}\n```\n* Ability to set the value of the element using \"property access\" syntax\n\nIn Groovy, getters and setters form what we call a \"property\", and offer a \nshortcut notation for accessing and setting such properties. So instead of the \nJava-way of calling getters / setters, you can use a field-like access notation: \n\n```groovy\nloginField.value = 'testUser'\n```\n\n* def\n\n```def``` means that the actual type of the value will be automatically inferred \nby the compiler. It eliminates the unnecessary boilerplate in variable \ndeclarations and makes your code shorter.\n\n```groovy\ndef loginWindow = $c(LoginWindow)\n```\n\n## Run tests\n\nPlease note that you need to download one of the latest versions of the web driver depending on the browser you want to use to testing.\nFor Chrome browser this is [chromedriver](http://chromedriver.chromium.org/downloads), for Firefox this is [geckodriver](https://github.com/mozilla/geckodriver/releases).\n\nTo run the test, first of all, you need to set ```cuba.testMode``` property to \ntrue in the `web-app.properties` file in the `web` module in your CUBA application. After that you \nshould start the application using Studio or Gradle tasks. To start application \nwith Gradle, run the following tasks in the terminal:\n\n    gradle setupTomcat deploy createDb start\n\nIf you run your tests in Chrome browser, you need to edit standard\ntest configuration for the test project in IntelliJ. To do so, click the \n*Select Run/Debug Configuration* button and select *Edit Configurations*  in the \ndrop-down list. In the VM options field, add the following:\n\n    -Dselenide.browser=chrome -Dwebdriver.chrome.driver=\u003cyour_path\u003e/chromedriver.exe\n\nwhere `\u003cyour_path\u003e` is the path to the chrome driver on your computer.\n\n![Create Configuration](images/testConfiguration.png)\n\nAfter that select the simple test or the test class you want to run, right \nclick on it and select *Debug* option.\n\nTo run the tests using Gradle, add the following task to the ```build.gradle``` file:\n\n```groovy\ntest {\n     systemProperty 'selenide.browser', System.getProperty('selenide.browser')\n     systemProperty 'webdriver.chrome.driver', System.getProperty('webdriver.chrome.driver')\n}\n```\n\nAfter that, run the following task in the terminal:\n\n    gradle test -Dselenide.browser=chrome -Dwebdriver.chrome.driver=\u003cyour_path\u003e/chromedriver.exe\n    \nwhere `\u003cyour_path\u003e` is the path to the chrome driver on your computer.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcuba-platform%2Fmasquerade","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcuba-platform%2Fmasquerade","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcuba-platform%2Fmasquerade/lists"}