This tutorial will get you started and have you Asserting Your Architecture! in a matter of minutes.
The steps that are covered include:
Contents |
You can get the library from one of two locations.
First, the easiest and most common method is to download the pre-compiled package from the downloads page.
Or, you can get the latest development commit from subversion. Details on accessing subversion are available on the source page. Note however, that the code in subversion is not always stable. Be sure to run the tests to find out.
For a list of the dependencies that you will need to download, see the dependencies list.
Next, you will create your architecture rules. This page will only discuss the XML configuration option, but be aware that you can also populate the configuration programmatically - or both with a configuration file and programmatically.
First, create the XML configuration file. The standard naming convention for this file is architecture-rules.xml but you are able to name this file whatever you want. Place this file in your classpath, such as src/test/resources.
Next, you’ll actually write your rules. This requires some thought. Think about your layers and modules and strive for separation of concern and loosely coupled modules. See the sample configuration example to write your rules.
First, note that if you are using the Ant task method of executing your test you don’t need to write the unit test. See the next section on writing the Ant task.
To write the unit test,
A complete, simple example looks like:
public class SimpleArchitectureTest extends AbstractArchitectureRulesConfigurationTest { /** * @see AbstractArchitectureRulesConfigurationTest */ public String getConfigurationFileName() { /** * Provide the name of the rules configuration file. * File file is loaded from the classpath. */ return "architecture-rules.xml"; } /** * @see AbstractArchitectureRulesConfigurationTest#testArchitecture */ public void testArchitecture() { /** * Run the test via doTest(). If any rules are broken, * or if the configuration can not be loaded properly, * then the appropriate Exception will be thrown. */ assertTrue(doTests()); } }
You may also opt to provide only programmatic configuration, and provide no xml configuration. To do this, call getConfiguration() which will return and instance of com.seventytwomiles.architecturerules.configuration.Configuration for you to setup. Once configured, again, implement testArchitecture() to call assertTrue(doTests());. A complete example looks like:
public class SimpleProgramaticArchitectureTest extends AbstractArchitectureRulesConfigurationTest { /** * Sets up the fixture, for example, open a network * connection. This method is called before a test * is executed. */ protected void setUp() throws Exception { super.setUp(); /* get the configuration reference */ final Configuration configuration = getConfiguration(); /* add sources */ configuration.addSource( new SourceDirectory("target\\test-classes", true)); /* set options */ configuration.setDoCyclicDependencyTest(false); configuration.setThrowExceptionWhenNoPackages(true); /* add Rules */ final Rule daoRule = new Rule("dao"); daoRule.setComment("dao may not access presentation."); daoRule.addPackage("test.com.seventytwomiles.dao.hibernate"); daoRule.addViolation("test.com.seventytwomiles.web.spring"); configuration.addRule(daoRule); } /** * @see AbstractArchitectureRulesConfigurationTest */ public String getConfigurationFileName() { /** * Provide the name of the rules configuration file. * File file is loaded from the classpath. */ return "architecture-rules.xml"; } /** * @see AbstractArchitectureRulesConfigurationTest#testArchitecture */ public void testArchitecture() { /** * Run the test via doTest(). If any rules are broken, * or if the configuration can not be loaded properly, * then the appropriate Exception will be thrown. */ assertTrue(doTests()); } }
If you would prefer to utilize Ant rather than write a unit test you may do so by grabbing the architecture-rules-ant module and defining a new taskdef for org.architecturerules.ant.AssertArchitectureTask.
Complete details for this Task can be found here.
By choosing to use the ant Task, you give up the ability to provide programmatic configuration. All configuration will be read from the XML configuration file.
Finally, you may mix programmatic and XML configuration. To do this, implement String getConfigurationFileName() to return “architecture-rules.xml” and continue to getConfiguraiton() in onSetup();. This will give you an instance of the configuration which is preloaded with the configuration found in the XML file. You may not programmatically add to or modify that configuration Write your Ant task
If you would prefer to utilize Ant rather than write a unit test you may do so by defining a new taskdef for com.seventytwomiles.architecturerules.ant.AssertArchitectureTask.
Complete details for this Task can be found here and the list of required dependencies is located here.
By choosing to use the ant Task, you give up the ability to provide programmatic configuration All configuration will be read from the XML configuration file. If you must provide programmatic configuration, there is still an alternative Ant route, that utilizes the junit task. Details are here.
//TODOThis is tool dependent. You probably know how to run your unit tests already.
Use your ant build, or IDE.