GWT unit tests allow you to test GWT components both from the commandline and inside Eclipse. Unit tests typically test a specific class or compilation unit, and use black-box testing; that is, they test the module as a functional unit, based on the public methods it exposes to the rest of the system.

Because Java is Java, it can take a little bit of elbow grease to get these working smoothly. The purpose of this page is to show you how to get started.

The tests, although authored in Java, are being transpiled to Javascript and run in a hidden browser.

The GWT unit tests live in the folder src/gwt/test/org. This folder mirrors the structure of src/gwt/src/org, and uses the same package names. To write a new test, do the following:

1. Note the name of the class for which you want to write tests. Let's say it's org.rstudio.core.client.Foo.

2. Create a new class with the name org.rstudio.core.client.FooTests, saved in src/gwt/test/org/rstudio/studio/client/FooTests.java

3. Write a class which derives from GWTTestCase and has method names that begin with test; you can simply follow the example in other classes in src/gwt/test.

4. Add your class to the unit test suite in RStudioUnitTestSuite.

That's all there is to it.

Tests can be run at the commandline using the ant unittest command. For instance:

$ ant unittest
Buildfile: /Users/jmcphers/rstudio/src/gwt/build.xml 

build-unittests:

unittest:
     [java] JUnit version 4.9b3
     [java] ....................
     [java] Time: 17.259
     [java]
     [java] OK (20 tests)
     [java]

BUILD SUCCESSFUL
Total time: 18 seconds

This ant target uses the RStudioUnitTestSuite configuration, so it will only run tests that have been added to that suite. You may wish to keep tests out of the suite until they are stable enough for all developers to run; see below for instructions on running individual tests.

Running ant unittest (warmed up) should take about 20 seconds. If it suddenly starts taking a lot longer, the most likely suspect is dependency injection. More background here: https://github.com/rstudio/rstudio/pull/4460

If you use Eclipse, you can write and run tests inside Eclipse. This shortens the feedback look when debugging failures and reduces context switches. Here's how to do it:

If you want to write your tests in Eclipse, you need to add the src/gwt/test folder to your project. Right-click on your project in Package Explorer and choose Build Path > Link Source...

Browse for your test folder (e.g. ~/you/git/rstudio/src/gwt/test). You should see test appear next to src as a source folder.

Next, we need to add JUnit to the build path so Eclipse can resolve code that references it. Right-click your project again and choose Build Path > Configure Build Path. Click the Libraries tab, then Add External Jars, and browse to src/gwt/lib/JUnit (version).jar. When you're done, you'll see JUnit appear in the Build Path.

Right-click on your test class file (FooTests) in Package Explorer and choose Run As > JUnit Test.

This will probably fail. Go to Run As > Run Configurations.... Click on the configuration four the test you are trying to run (for instance FooTests), and then click on the Classpath tab. In that tab, repeat the following for the client and test source folders:

1. Click Advanced
2. Click Add Folders
3. Browse for the folder

Next, click Add External Jars and browse for the JUnit jar file in src/gwt/lib.

When you're done, your test run configuration should look like this:

You should now be able to Run As > JUnit Test and see test results.

Lint list:

• Support for plain JUnit unit tests for modules that don't need GWT (GWT test cases are slow).
• It'd be nice if there were a way to run a single test or set of tests from the commandline.
• It's hard to debug test failures.
• The HTMLUnit test runner emits a lot of unhelpful warnings.