Dev guide: Unit testing

All code submitted needs to be accompanied by working JUnit tests which cover its functionality. The naming scheme for test classes is: <ClassName>Test. For instance, the HierholzerEulerianCycle class has a corresponding test class HierholzerEulerianCycleTest. Test classes also need a copyright header. Tests should not require any network resources; if you've already gotten everything working with full network connectivity, you should then be able to unplug your network cable, walk into a Faraday cage on Mars, type mvn test, and see BUILD SUCCESS at the end.

Please use JUnit 5 annotations for all test cases. Also, whenever applicable, use assertions in your code.

Slow Running Tests

Some tests in the library require a considerable amount of time since they are verifying algorithmic correctness over a large number of graph instances. Such tests are separated from the rest using @Tag("slow") and are not executed by default when issuing mvn test. These slow tests are only executed during the integration-test phase of the Maven lifecycle. Thus, you can execute the full test suite including these slow tests by issuing mvn verify. Make sure that you do that before submitting a pull-request.

Optional Tests

Certain tests cannot be run even during the integration-test phase, either because they are excessively slow, or they require resources that may not be universally available. Such tests should be annotated with @Tag("optional"). There is no need to run these tests before submitting a pull-request. If you do want to run them, you can either execute them individually via your IDE, or via a mvn command as described below.

Running Tests

You can use the following common examples to run tests from the command line:

• mvn test: all fast-running unit tests
• mvn verify: all unit and integration tests
• mvn -Dtest=PerformanceTestSuite test: run all performance tests
• mvn -Dtest=CycleDetectorTest test: run all tests in the named class
• mvn -Dtest=CycleDetectorTest#testDirectedWithCycle test: run the single test method specified in the named class
• mvn -DexcludedGroups="" verify: all tests, including optional ones
• mvn -DexcludedGroups="" -Dtest=BergeGraphInspectorTest#checkPappusGraph test: run the single optional test method specified in the named class

There are additional variations as well. Due to the way the surefire plugin works when multiple projects are present, if you run with the -Dtest option from the top level, mvn will report a BUILD FAILURE regardless of the test results. To avoid this, (a) run from the relevant subdirectory such as jgrapht-core or (b) use the -DfailIfNoTests=false flag.

To get full stack traces for exceptions, use the -DtrimStackTrace=false flag.