|
|
| Line 1: |
Line 1: |
| − | [[Category:Virgo]] [[Category:EclipseRT]]
| |
| | {{Virgo}} | | {{Virgo}} |
| | | | |
| | = Version Control = | | = Version Control = |
| | | | |
| − | Virgo uses [[Git|git]]. | + | Virgo uses [[Git|git]]. |
| | | | |
| − | = Coding = | + | = Coding = |
| | | | |
| − | Virgo has a strong emphasis on maintainable, or "clean", code. If you need a really good introduction to coding, we recommend "[http://cc2e.com/ Code Complete]". If you are already a proficient programmer and want to write really clean code, read "[http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882 Clean Code]". If you are not an expert in writing Java, read "[http://java.sun.com/docs/books/effective/ Effective Java]". | + | Virgo has a strong emphasis on maintainable, or "clean", code. If you need a really good introduction to coding, we recommend "[http://cc2e.com/ Code Complete]". If you are already a proficient programmer and want to write really clean code, read "[http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882 Clean Code]". If you are not an expert in writing Java, read "[http://java.sun.com/docs/books/effective/ Effective Java]". |
| | | | |
| − | Virgo code is thread safe unless specifically stated. Achieving thread safety in Java is not easy. We recommend "[http://www.javaconcurrencyinpractice.com/ Java Concurrency in Practice]" for a good grounding in Java concurrency. | + | Virgo code is thread safe unless specifically stated. Achieving thread safety in Java is not easy. We recommend "[http://www.javaconcurrencyinpractice.com/ Java Concurrency in Practice]" for a good grounding in Java concurrency. |
| | | | |
| − | = Testing = | + | = Testing = |
| | | | |
| − | Virgo also has a strong emphasis on testing. Unit tests check the behaviour of individual classes or small groups of classes. Integration tests check the behaviour of groups of Virgo bundles running together in Equinox. System verification tests (SVTs), including some simple performance tests, check the behaviour of packaging builds of the kernel and web server from a user's perspective.
| + | see ... |
| | | | |
| − | [http://www.junit.org/ JUnit] is used for all these types of tests. Each testcase is structured as a class with class name ending in <tt>Tests</tt>. Tests typically reside in the <tt>src/test/java</tt> folder of a project.
| + | = IP Due Diligence = |
| | | | |
| − | If you need a thorough introduction to Test Driven Development, we recommend "[http://www.growing-object-oriented-software.com/ Growing Object-Oriented Software Guided by Tests]". This book makes the important point that unless test code is as clean as the code under test, the tests will inevitably end up slowing down the whole project. Good test coverage enables changes to be made with confidence, so test code should be refactored and kept clean just like the code under test.
| + | == Raising "works with" CQs == |
| | | | |
| − | == Unit Tests ==
| + | "works with" CQs are required for test dependencies which are not distributed with Virgo or checked in to Eclipse version control (git, svn, cvs). |
| | | | |
| − | Each unit test tests a small unit, typically a single class. Dependencies are usually stubbed or mocked out.
| + | The initial set of test dependencies was determined, for repositories which are built with ant, as follows: |
| | | | |
| − | Stubs are hand-written, dummy implementations of interfaces just sufficient to simulate the behaviour of a full implementation of the interface and in some cases to check that the interface has been used correctly. Stubs for several standard OSGi interfaces are provided in the [http://git.eclipse.org/c/virgo/org.eclipse.virgo.osgi-test-stubs.git/tree/ OSGi Test Stubs] git repository. Other projects may supply stubs for commonly used interfaces. For example, the Quasi Framework interfaces have stubs [add link once kernel checked in] provided.
| + | 1. In the build-xxx directory run ant report |
| | | | |
| − | Mocks are generated on the fly from interfaces. [http://easymock.org/ EasyMock] is typically used. Expectations of how an interface is used can be set and checked. It is important not to code expectations that are too specific to an implementation otherwise the resultant test will be fragile and is likely to break if the implementation being tested is refactored.
| + | 2. Extract a raw list of the test dependency jars |
| − | | + | <pre>find <report directory> -name "*-test.xml" -exec grep -E \/.+\.jar {} \; >test-jars.txt |
| − | Some tests of complex classes use a combination of stubs and mocks.
| + | |
| − | | + | |
| − | In general, unit tests aim to provide at least 80% coverage of Virgo code, but some components fall short of this and more tests need to be written. The precommit ant target used to check coverage using Clover, but this check is not currently supported as the Eclipse Hudson server does not support Clover.
| + | |
| − | | + | |
| − | Some complex classes are simply too messy to unit test and refactoring is required to enable maintainable unit tests to be created. So if significant refactoring of existing code is planned, that is often a good time to add a suite of unit tests.
| + | |
| − | | + | |
| − | New code should be written with unit tests from the start. This is the only way to make sure that code can be thoroughly unit tested.
| + | |
| − | | + | |
| − | == Integration Tests ==
| + | |
| − | | + | |
| − | Integration tests install a collection of bundles into Equinox and then run the testcase as part of a bundle. Some integration tests install sufficient bundles to start a Virgo kernel or web server, but others install a relatively small subset.
| + | |
| − | | + | |
| − | An integration test framework is provided in the Virgo Test git repository.
| + | |
| − | | + | |
| − | == Automated Testing ==
| + | |
| − | | + | |
| − | Test dependencies are either checked in to <tt>src/test/resources</tt> or are downloaded into an Ivy repository when the tests are built.
| + | |
| − | | + | |
| − | The unit and integration tests of a Virgo git repository can be run by changing into the <tt>build-xxx</tt> directory and issuing:
| + | |
| − | <pre>ant clean clean-integration test
| + | |
| − | </pre>
| + | |
| − | This will halt when the first test fails. To run all the tests and not halt on failure, issue:
| + | |
| − | <pre>ant -Dci.build=true clean clean-integration test
| + | |
| | </pre> | | </pre> |
| − | and, since this will always report "build successful", remember to open <tt>target/test-results/index.html</tt> at the end to see which tests passed and which failed.
| + | 3. Edit test-jars.txt using an editor with a regular expression global change facility and do the following global changes. |
| | | | |
| − | == System Verification Tests ==
| + | 3.1 Replace regex .+\/(.+)\.jar\"> with $1.jar. |
| | | | |
| − | SVTs are present in the Virgo Kernel System Verification Tests and the Virgo System Verification Tests repositories. Building these repositories runs the test. The latter project requires a package web server zip file to be placed in <tt>build-svt/target/artifacts/</tt> before the following ant target is run:
| + | 3.2 Replace regex .+\/(.+)\.jar\"\/> with $1.jar. |
| − | <pre>ant test-svt
| + | |
| − | </pre>
| + | |
| − | == Performance Tests ==
| + | |
| | | | |
| − | A small number of SVTs in the Virgo Performance Tests git repository check that the performance of Virgo does not worsen. These tests are very approximate since it is impossible to enforce precise performance goals when tests are run in a general CI server which may be subject to fluctuation in its load and performance.
| + | 3.3 Replace -sources with the empty string |
| | | | |
| − | == Ignoring Tests ==
| + | 4. Sort test-jars.txt and remove duplicate lines. |
| | | | |
| − | Ignoring a failing test is always a last resort. If this is required, then a bug must be raised and the failing test method or, in rare situations, the whole test class should be annotated using the <tt>org.junit.Ignore</tt> annotation:
| + | 5. Look through test-jars.txt and raise "works with" for any JARs which don't have a Virgo CQ for the correct version. Also, raise corresponding Virgo bugzillas and set the iplog flag to enter the bugzillas in the automated IP log. |
| − | <pre>@Ignore("bug <bugzilla number>: <reason for ignoring the test>")
| + | |
| − | </pre>
| + | |
| − | The bug should also detail which test or tests are ignored.
| + | |
| | | | |
| − | = IP Due Diligence =
| + | [[Category:Virgo]] [[Category:EclipseRT]] |
| − | | + | |
| − | == Raising "works with" CQs ==
| + | |
| − | | + | |
| − | "works with" CQs are required for test dependencies which are not distributed with Virgo or checked in to Eclipse version control (git, svn, cvs).
| + | |
| − | | + | |
| − | The initial set of test dependencies was determined, for repositories which are built with ant, as follows:
| + | |
| − | | + | |
| − | 1. In the build-xxx directory run ant report
| + | |
| − | | + | |
| − | 2. Extract a raw list of the test dependency jars
| + | |
| − | <pre>find <report directory> -name "*-test.xml" -exec grep -E \/.+\.jar {} \; >test-jars.txt
| + | |
| − | </pre>
| + | |
| − | | + | |
| − | 3. Edit test-jars.txt using an editor with a regular expression global change facility and do the following global changes.
| + | |
| − | | + | |
| − | 3.1 Replace regex .+\/(.+)\.jar\"> with $1.jar.
| + | |
| − | | + | |
| − | 3.2 Replace regex .+\/(.+)\.jar\"\/> with $1.jar.
| + | |
| − | | + | |
| − | 3.3 Replace -sources with the empty string
| + | |
| − | | + | |
| − | 4. Sort test-jars.txt and remove duplicate lines.
| + | |
| − | | + | |
| − | 5. Look through test-jars.txt and raise "works with" for any JARs which don't have a Virgo CQ for the correct version. Also, raise corresponding Virgo bugzillas and set the iplog flag to enter the bugzillas in the automated IP log.
| + | |
Virgo has a strong emphasis on maintainable, or "clean", code. If you need a really good introduction to coding, we recommend "Code Complete". If you are already a proficient programmer and want to write really clean code, read "Clean Code". If you are not an expert in writing Java, read "Effective Java".
Virgo code is thread safe unless specifically stated. Achieving thread safety in Java is not easy. We recommend "Java Concurrency in Practice" for a good grounding in Java concurrency.
"works with" CQs are required for test dependencies which are not distributed with Virgo or checked in to Eclipse version control (git, svn, cvs).
The initial set of test dependencies was determined, for repositories which are built with ant, as follows:
1. In the build-xxx directory run ant report
2. Extract a raw list of the test dependency jars
3. Edit test-jars.txt using an editor with a regular expression global change facility and do the following global changes.
3.1 Replace regex .+\/(.+)\.jar\"> with $1.jar.
3.2 Replace regex .+\/(.+)\.jar\"\/> with $1.jar.
4. Sort test-jars.txt and remove duplicate lines.
5. Look through test-jars.txt and raise "works with" for any JARs which don't have a Virgo CQ for the correct version. Also, raise corresponding Virgo bugzillas and set the iplog flag to enter the bugzillas in the automated IP log.
