CORA - Tutorial

Posted by Benoît "badetitou" Verhaeghe on July 5, 2017

/!\ THE PROJECT IS NOW CALLED SmartTest. You can find it here /!\

What is CORA ?

CORA is a plugin developed in Pharo. It is an Add-On for Quality Assistant by Yuriy Tymchuk and provides new rules and critiques.

The goal of CORA is to provide to the developers the list of tests they should run after they modify their code. With this plugin installed, developers will save time and will develop in a better way (hopefully).

Installation

In an old image

I supposed you already install Pharo. If not, please install it.

To install CORA. The easiest way is to execute the following code in a Playground.

Metacello new
  githubUser: 'badetitou' project: 'CORA' commitish: 'master' path: '.';
  baseline: 'CORA';
  load.

From the version 7 of Pharo. Developers use Calypso as Pharo browser. So we provide this command to install CORA with the compatibility mode for Calypso. It will also install the last version of Calypso !!!

Metacello new
  githubUser: 'badetitou' project: 'CORA' commitish: 'master' path: '.';
  baseline: 'CORA';
  load: 'calypso'.

The installation can take few minutes because CORA needs to use the Sista Compiler. So I need to recompile all the code.

With Continuous Integration (jenkins)

If you’d like to use a preconfigured image with CORA and optimize for your work. You can use the integration with Jenkins I’ve made. You only have to add these lines into your configuration.

./pharo $PROJECT_NAME.image eval --save "
  Metacello new  
    baseline: #CORA;
    githubUser: 'badetitou' project: 'CORA' commitish: '$VERSION' path: '.';
    onWarningLog;
    load".

./pharo $PROJECT_NAME.image eval --save "
	CORATestCoverageTestFinderStrategy prepareInJenkinsForPackagesNamed: #('CORA')
  ".

You have to change the last line by replacing #('CORA') by list of packages corresponding to your project. You should change $VERSION by master if you want to work only with the stable version of CORA. Or by development for the development version of CORA.

Help us

I’m also working on test usage habit. If you’d like to use CORA and in the same time help us (because it’s awesome ;) ). Please use this command :

Metacello new
  githubUser: 'badetitou' project: 'TestsUsageAnalyser-CORAExtends' commitish: 'master' path: '.';
  baseline: 'TestsUsageAnalyserCORAExtends';
  load.

It will install a spy that will record data for analysis (No data divulgation, don’t worry) and CORA for Nautilus. If you want to install the version for Calypso in the same time.

Metacello new
  githubUser: 'badetitou' project: 'TestsUsageAnalyser-CORAExtends' commitish: 'master' path: '.';
  baseline: 'TestsUsageAnalyserCORAExtends';
  load: 'calypso'.

Utilisation

Once you install CORA, it is auto-activated (it can take a few seconds, but you will not notice them).

Each time you select a method or a class. Two rules can be activated.

Should write tests

shouldWrtieTest

This critique indicates that the plugin didn’t find any test related to the method you’ve selected. Normally, it means you didn’t write a test for this method. So it advises you to create a test (because yes… It’s essential !!!).

If you click on the fix button. The plugin offer you to create it quickly (from a template).

Should run tests

shouldRunTest

This critique indicates that the plugin has found test(s) related to the method you’ve selected. This critique offer you two new actions

  • By clicking on the #testNotRun icon, the plugin will execute the tests related to the method. If there are errors or fails, the button will turn red or yellow (but the debugger will not be displayed !!!).
  • By clicking on the #smallWindow icon, the plugin will open a new window with the test it’s found.
AutoTestSelection

This window displays the list of tests CORA has found. You’re able to run each run by clicking on the #testNotRun icon. The tests will be run in debug mode (errors will be displayed). By clicking on the “Run all test” button, you will run all the tests displays in debug mode.

Options

Many options are available to custom your experience with CORA. You should read this part to use CORA at the maximum of its possibilities. You can extend each option and so create your own experience.

Testing strategy

Testing strategy

CORA provides four strategies for testing.

  • Never will only display the button as describe previously.
  • Always will execute all the test CORA finds as soon as it finds the tests. If you change a method A then select a method B before end the research of relative tests, CORA will continue to search and run the tests as soon as it finds them.
  • Every 5 Minutes will collect the tests CORA find during a duration of 5 minutes. Then CORA will run the tests and, if a test fails, CORA will display a window with the test suite it ran.
  • Each modification will run the tests CORA find each time you modify your code. This is the default strategy. As for always strategy, if you change a method A and select a method B before the end of the research of relative tests, then CORA will continue to search and run the tests as soon as it finds them.

You’re able to extend CORATestingStrategy if you’d like to create your own testing strategy.

Finder

finder

The finder contains the implementation of how CORA will find test relative to a method. The default will work as follow, for

  • a method, it will use the current change impact strategy (see Change Impact strategy).
  • a class, it will search the method that use the variables of the class.
  • a test method, it will provide the test method
  • a setup, it will provide all the tests concerning by this setup
  • a teardown, it will provide all the tests concerning by this teardown

You’re able to extend CIPackagesFilter if you’d like to create your own strategy to filter tests.

Filter

filter

Because we’re using ChangeImpact. You can also define filter for the finder strategy to optimize our tool. Currently we are filtering test relative to the method package. That include all the class in our package, the package with the same base name (“CORA-Patate” and “CORA-Frite-Poulet” are two packages with the same base name “Cora”). And the package that call our method class (“MyClass»#hello” is in the package A. In the package B, there is at least a method that calls “MyClass”. So, the methods inside the package B are not rejected).

(working on schema)

You’re able to extend CIPackagesFilter if you’d like to create your own strategy to filter tests.

Change Impact strategy

change_impact_strategy

Currently, CORA uses Change Impact by Julien Delplanque to explore the code. The implementation of CORA is simple. We simply research the senders of the method you select and the senders of the senders … Each time, it verify that the senders are not filtered by the filter.

You’re able to extend CIStrategy if you’d like to create your own strategy to find tests.

Runner

runner

The runner is the part of CORA which run the tests provided by the finder. By default the SmartRunner is used.

  • If you click on “run button” of the critique, it will run the found tests and change its color depending of the result (green, yellow or red).
  • On the “Run All Button” or on the method button, the test will be run in debug mode (so if they fail, or raise an error, the debugger will open).

The Debug one will open the debugger if an error appears (don’t depend of the button you click on). The notice one works as the debug one but it never opens the debugger.

Uninstall

To uninstall CORA, it’s a bit hard currently. You have to follow this instruction:

  • (Disable TUA in the settings)
  • (Unload TUA)
  • Unload CORA
  • Run this command in a playground ReRuleManager cleanUp
  • ReLoad Kernel
  • Reload SUnit-Core
  • Reload QualityAssistant
  • Reload Nautilus

The projects is present on github. So you can report issues (or features you want to see implemented). And you can do pull request too.

Development version

We’re migrating on github. Currently only the development version is present on github. You can test it by running this command in a Playground.

Metacello new
  githubUser: 'badetitou' project: 'CORA' commitish: 'development' path: '.';
  baseline: 'CORA';
  load.

To download the version with Calypso.

Metacello new
  githubUser: 'badetitou' project: 'CORA' commitish: 'development' path: '.';
  baseline: 'CORA';
  load: 'calypso'