Skip to content
recheck for web apps – the Git for the GUI.
Branch: master
Clone or download
Latest commit e7e1903 Jun 18, 2019

README.md

-web Tweet

Price Build Status Latest recheck-web on Maven Central license PRs welcome code with hearth by retest

recheck-web is a Golden Master-based test framework on top of Selenium that allows for easy creation and maintenance of more complete and nearly unbreakable tests.

Features

  • Easy creation and maintenance of checks for web.
  • Semantic comparison of contents.
  • Easily ignore volatile elements, attributes or sections, using a git-like syntax.
  • Simple maintenance to update Golden Masters with intended changes, using our GUI or CLI.
  • No unexpected changes go unnoticed.
  • Operates on top of Selenium.
  • Makes your tests unbreakable.
  • The Git for your GUI.

Advantages

Instead of manually defining individual aspects that you want to check, check everything at once. So instead of writing many assert statements—and still not have complete checks—write a single re.check(). This saves a lot of effort when creating tests. And it makes sure to not miss unexpected changes.

Even better: Using review or the open-source recheck.cli, you can easily accept those changes with a single click (patent pending). This also saves a lot of time during maintenance. Moreover, any regular changing aspects or elements (e.g. date fields) can easily be ignored.

And, using the Golden Master, recheck-web can identify elements even after the identifying attribute was changed. So assume you are using, e.g. an HTML id property to identify an element within your Selenium test. Now, assume that this id property changes within the HTML. Then, your test would break, resulting in an NoSuchElementException. But using RecheckDriver as a drop-in replacement/wrapper of your normal driver magically finds the element and logs a warning such as

*************** recheck warning ***************
The HTML id attribute used for element identification changed from 'intro-slider' to 'introSlider'.
retest identified the element based on the persisted old state.
If you apply these changes to the state , your test  will break.
Use `By.id("introSlider")` or `By.retestId("9c40281d-5655-4ffa-9c6d-d079e01bb5a3")` to update your test.

Prerequisites

Operates on top of Selenium. Selenium has become an official W3C standard, supported by all major browsers. Learn more about Selenium and how to install it.

recheck-web leverages recheck, which is available as a Java API with support for JUnit 4 and JUnit 5 as well as TestNG.

Setup

Add recheck-web as dependency through Maven Central: Latest recheck-web on Maven Central

<dependency>
  <groupId>de.retest</groupId>
  <artifactId>recheck-web</artifactId>
  <version><!-- latest version, see above link --></version>
</dependency>

A tutorial about how to setup recheck-web can e.g. be found on DZone, together with a follow-up article about how to make your Selenium tests almost "unbreakable".

Usage of plain recheck

Then replace the assertions in your Selenium test. An example test could look like so (simplified):

public class MyRecheckWebTest {

  private WebDriver driver;
  private Recheck re;

  @Before
  public void setUp() {
    driver = new ChromeDriver();
    
    // Use the default implementation.
    re = new RecheckImpl();
  }

  @Test
  public void index() throws Exception {
    // Set the file name of the Golden Master.
    re.startTest( "my-file-name" );

    // Do your Selenium stuff.
    driver.get( "https://my-url.org/" );

    // Single call instead of multiple assertions (doesn't fail on differences).
    re.check( driver, "my-step-name" );

    // Conclude the test case (fails on differences).
    re.capTest();
  }

  @After
  public void tearDown() {
    driver.quit();
    
    // Produce the result file.
    re.cap();
  }
}

Running such a test for the first time will result in a failure with an output like so:

java.lang.AssertionError: Found 1 differences in 1 checks of which 1 are unique: [No Golden Master found.]

Details: 
test simple-showcase has 1 differences (1 unique): 
No Golden Master found. First time test was run? Created Golden Master now, don't forget to commit...

	at de.retest.recheck.RecheckImpl.capTest(SourceFile:135)
	at de.retest.web.it.SimpleRecheckShowcaseIT.index(SimpleRecheckShowcaseIT.java:61)
	at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
...

Running such a test will also create a folder structure containing a retest.xml file and a screenshot per check (depending on your chosen names and configuration). This contains the Golden Master against which future executions of this test are compared. If you use version control, you should commit those files. Note that the retest.xml contains a full description of the rendered website, including all relevant information such as text, source, etc. and all non-default CSS attributes such as font and margin. Although these files may become large, they are smaller than the original and by ignoring specific (or all) attributes, you can configure how large they are. Anyways, storing a few kilobyte extra is much cheaper than the manpower needed to manually specify checks.

Executing the same test again should not result in any differences. But after changing the website and executing the test, you should see the test reporting your changes.

E.g. if you change a single CSS rule, you will find all elements that are affected by this change. Like so:

java.lang.AssertionError: Found 8 differences in 1 checks of which 2 are unique: [color: expected="rgb(65, 65, 65)", actual="rgb(0, 0, 0)", border-color: expected="rgb(65, 65, 65)", actual="rgb(0, 0, 0)"]

Details: 
test showcase has 8 differences (2 unique): 
index resulted in: 
	EM [Have you had enough]:
		border-color, color: expected="rgb(65, 65, 65)", actual="default"
	EM [Use an artificially intelligent]:
		border-color, color: expected="rgb(65, 65, 65)", actual="default"
	EM [to fully automatically test your application.]:
		border-color, color: expected="rgb(65, 65, 65)", actual="default"
	EM [No need to create assertions]:
		border-color, color: expected="rgb(65, 65, 65)", actual="default"
	EM [retest compares the whole picture instead of a single piece of the puzzle.]:
		border-color, color: expected="rgb(65, 65, 65)", actual="default"
	EM [The future of testing is in AI.]:
		border-color, color: expected="rgb(65, 65, 65)", actual="default"
	EM [The future of testing is now]:
		border-color, color: expected="rgb(65, 65, 65)", actual="default"

Additionally, a file named ${TEST_CLASS_NAME}.report will be created upon test failure, typically located in your target/test-classes folder. This file can now be used to apply those changes to your Golden Master, using either the review or the recheck.cli.

Usage of RecheckDriver / "Unbreakable Selenium"

In order to use "Unbreakable Selenium", you just need to wrap your usual driver within a RecheckDriver (drop-in replacement) and use RecheckWebImpl instead of RecheckImpl. The code would the look like so):

 // Use the RecheckDriver as a wrapper for your usual driver.
 driver = new RecheckDriver( new ChromeDriver() );

 // Use the unbreakable recheck implementation.
 re = new RecheckWebImpl();

License

This project is licensed under the AGPL license.

You can’t perform that action at this time.