CMPE212 – Reminders Assignment 2 due this Friday. Winter 2019 CMPE212 4/30/2019 CMPE212 – Reminders Assignment 2 due this Friday. Next Quiz two weeks after Reading Week. Winter 2019 CMPE212 - Prof. McLeod Prof. Alan McLeod

Today Javadoc Documentation. Winter 2019 CMPE212 4/30/2019 Today Javadoc Documentation. Adding the JUnit5 library to your Assn 3 project in Eclipse. Start JUnit Testing. Winter 2019 CMPE212 - Prof. McLeod Prof. Alan McLeod

Fall 2013 CMPE212 Javadoc Javadoc.exe is a program that comes with the JDK. (It is in the same directory as javac.exe and java.exe – the “bin” folder). It is not included in the JRE only. If I have written a class, “MyClass.java”, that contains properly formatted comments (more below), then running “javadoc MyClass.java” generates a file “MyClass.html”. (And lots of other files, actually.) The html file contains external documentation generated from the formatted comments in the source code. Winter 2019 CMPE212 - Prof. McLeod Prof. Alan McLeod

Javadoc - Cont. Normal block comments in Java are delimited by “/*” and “*/”. Everything between these delimiters, usually multiple lines, is a comment. Javadoc block comments are delimited by “/**” and “*/”. Winter 2019 CMPE212 - Prof. McLeod

Javadoc - Cont. The general form of a Javadoc comment: /** * Summary sentence. * More general information about the * class, attribute or method which * follows the comment, using as many lines * as necessary. (html tags can be included) * * javadoc tags to specify more specific * information, such as parameters and * return values for a method */ Winter 2019 CMPE212 - Prof. McLeod

Javadoc - Cont. The general form of a Javadoc tag is: @tagName comment The tags you use depend on what you are describing (class, method or attribute). In the case of methods, you can have a tag for each parameter, the return value, and a tag for each thrown exception. Eclipse (really nice!!) will generate a blank tag for you after you type “/**”. Typically, you will only write javadoc comments for public attributes and methods… Winter 2019 CMPE212 - Prof. McLeod

Eclipse Javadoc Assist For example, if you have the method header: public static double[] generateRandomArray(int size) Type /** right above this line and press <enter>. You will get: /** * * @param size * @return */ Winter 2019 CMPE212 - Prof. McLeod

Eclipse Javadoc Assist, Cont. Then you have to finish the comment: /** * Generates an array of random doubles. * * The method uses the Math.random() method to generate * an array of doubles between 0.0 and 1.0. * @param size The desired size of the array. * @return The array of random doubles. */ Winter 2019 CMPE212 - Prof. McLeod

Eclipse Javadoc Assist, Cont. Hold your cursor over the method header and you will get a preview of what the processed Javadoc will look like: (Or view the Javadoc tag in the same view as the Console tag.) Winter 2019 CMPE212 - Prof. McLeod

Common Javadoc Tags @param Parameter_name description @throws Exception_name description @return description @see packageName.ClassName, packageNamme.ClassName#methodName, etc. @author @version Winter 2019 CMPE212 - Prof. McLeod

Javadoc - Cont. Html tags can also be added to the comments to add more formatting to the resulting document: <em> for emphasis <code> for code font <img> for images <ul><li> </li></ul> for bulleted lists Etc… Winter 2019 CMPE212 - Prof. McLeod

Javadoc Reference The best reference for javadoc is at: http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html Winter 2019 CMPE212 - Prof. McLeod

Javadoc - Cont. The output from Javadoc looks exactly like the API documentation you have already seen - since that is the way it has been generated! The advantage is that when source code is changed, the Javadoc comments can be changed in the source, at the same time. The external documentation is then easily re-generated. Javadoc also provides a consistent look and feel to these API documents. Winter 2019 CMPE212 - Prof. McLeod

Javadoc - Cont. Most modern IDE’s (like NetBeans and Eclipse) allow you to run Javadoc from within the environment, and provide tools and wizards to help you create comments. In Eclipse, select “Project”, then “Generate Javadoc…”. Let’s run javadoc on the Halloween5 class. (Note that the first time you do this, you will have to tell Eclipse where javadoc.exe resides.) Winter 2019 CMPE212 - Prof. McLeod

Testing in Assignment 3 You are supplied with JUnit5 testing programs to test your Pizza and LineItem classes. JUnit testing is the established and best way to test Java programs. JUnit testing will be covered in class, but you don’t need to understand JUnit testing to run the testing programs – you do not need to write any new tests and should not modify the existing tests. Winter 2019 CMPE212 - Prof. McLeod

Testing in Assignment 3, Cont. To run the supplied tests you will need to link the JUnit 5 library to your assignment 3 project. The wizard that creates a JUnit testing class can do this for you or you can: First, right click on the project name, choose “Build Path”, then “Add Libraries…” Winter 2019 CMPE212 - Prof. McLeod

Testing in Assignment 3, Cont. Choose “JUnit”. Then “Next >”. Winter 2019 CMPE212 - Prof. McLeod

Testing in Assignment 3, Cont. On the next screen, make sure that JUnit 5 is chosen and click on “Finish”. You should now see the additional library listed with your project. Winter 2019 CMPE212 - Prof. McLeod

Testing in Assignment 3, Cont. If you already have the testing classes in your project, then all those compilation errors in the testing class should go away! You can run the JUnit testing files on their own. The “suite” program just runs both of them together. Winter 2019 CMPE212 - Prof. McLeod

Testing Until now “we” have used another class with a main method to run tests on the class we have “harnessed” for testing. See TestHalloween4.java and TestHalloween5.java for example. JUnit is a framework designed for this kind of work and it is very easy to use in Eclipse. Winter 2019 CMPE212 - Prof. McLeod

JUnit Testing Best reference is https://junit.org/junit5/ For use in Eclipse see: “Java development user guide” > “Getting Started” > “Basic tutorial” > “Writing and running JUnit tests”. Winter 2019 CMPE212 - Prof. McLeod

JUnit Testing in Eclipse In the project containing the class(es) you wish to test, add a Testing class by choosing “New JUnit Test Case”. Name the class and choose the classes to be tested. Choose extra stubs, if needed. Winter 2019 CMPE212 - Prof. McLeod

JUnit Testing in Eclipse, Cont. Next, let the wizard create test method stubs in your testing class for all methods you wish to test: Winter 2019 CMPE212 - Prof. McLeod

JUnit Testing in Eclipse, Cont. Allow the wizard to add the JUnit library to the Build Path, if prompted. Winter 2019 CMPE212 - Prof. McLeod

JUnit Testing in Eclipse, Cont. Fill in the method stubs with tests. You can have multiple tests in a method or multiple methods or both, as required. Diagnosis might be easier if you have one test per method. You could end up with hundreds of tests, just for one object! See Halloween5Test.java. It contains one test that will not pass – just to show what a failed test looks like. Winter 2019 CMPE212 - Prof. McLeod

JUnit 5 Assertions Use (expected, actual) or (expected, actual, String). The optional argument is a string message that would describe what is being tested. assertArrayEquals() assertEquals() assertFalse() assertNotEquals() assertNotNull() assertNull() assertTrue() Winter 2019 CMPE212 - Prof. McLeod

IllegalHalloweenException.class JUnit 5 Assertions, Cont. Use assertThrows() to make sure an exception is thrown when it should be. This assertion uses two arguments that are built using syntax we have not yet discussed. The two are arguments are a Class object and an Executable object. The Class object: Any object has a .class constant attribute that supplies the Class object. So we will use: IllegalHalloweenException.class to supply the Class object for the first argument, the expected exception type. Winter 2019 CMPE212 - Prof. McLeod

JUnit 5 Assertions, Cont. The second argument is the Executable object. This will contain the code that is supposed to throw the identified exception. It is easiest to construct this object using a Lambda Function. Which we will discuss, just not yet! () -> new Halloween5(badYear, numKids, temps, condition) Winter 2019 CMPE212 - Prof. McLeod

Halloween5Test.java, Cont. Uses setup and teardown methods. Also uses assertThat (for a silly test…). Winter 2019 CMPE212 - Prof. McLeod

assertThat() Takes a Matcher<T> object for its second (or third) parameter. Possible object types: AllOf, AnyOf, BaseMatcher, CombinableMatcher, CustomMatcher, CustomTypeSafeMatcher, DescribedAs, DiagnosingMatcher, Every, FeatureMatcher, Is, IsAnything, IsCollectionContaining, IsEqual, IsInstanceOf, IsNot, IsNull, IsSame, StringContains, StringEndsWith, StringStartsWith, SubstringMatcher, TypeSafeDiagnosingMatcher, TypeSafeMatcher Winter 2019 CMPE212 - Prof. McLeod

assertThat(), Cont. For example (from JUnit.org): And, there is a: assertThat("albumen", both(containstring("a")).and(containsString("b")) And, there is a: import static org.hamcrest.CoreMatchers.*; See also: https://stackoverflow.com/questions/43280250/how-do-i-use-hamcrest-with-junit-5-when-junit-5-doesnt-have-an-assertthat-fun Winter 2019 CMPE212 - Prof. McLeod

assertThat, Cont. Note that the order is different - the actual comes first followed by the expected. You can still have a String message as the first parameter. You can build more sophisticated assertions with this method. Winter 2019 CMPE212 - Prof. McLeod

Some JUnit Annotations Annotations are needed to help the testing framework understand the purpose of the methods in the testing class and how (and how often) they should be run: @Test is used most often and it identifies a method that is a JUnit test. Methods without this annotation will not be considered tests, although they can be invoked from methods that are tests. Winter 2019 CMPE212 - Prof. McLeod

More JUnit Annotations - Setup and Teardown Use @BeforeEach annotation with methods that will run before every test. Similarly @AfterEach for methods to run after every test. @BeforeAll runs once before all tests. @AfterAll runs once after all tests. Winter 2019 CMPE212 - Prof. McLeod

No try/catch Don’t bother with try/catch blocks. If you are testing code that has a throws decoration, then just have your unit test method throw Exception to satisfy the compiler. If an exception is thrown unexpectedly (a run-time error!) you will get a different kind of failure notice in the report. Note that the testing does not stop! Winter 2019 CMPE212 - Prof. McLeod

Test Suites You can combine separate JUnit testing classes into a single suite and run them all at once. In Eclipse, go “New”, “Other”, “JUnit”, “JUnit Test Suite”. This does not work properly in Eclipse and the JUnit5 instructions are not consistent! But you will not need to build a suite. Specify the src folder location for the existing testing *.java files and choose the ones you want to include in the suite. See AllTests.java. Winter 2019 CMPE212 - Prof. McLeod