• Jobs
  • About
  • Creating your Java project workspace February 6, 2009

    Why “plan” your project structure?

    By planning your project structure we mean organizing your directories and files and checking them in your code base. Even though there are a few guidelines around organizing project files, there are some best practices that worked for me well in the past. Some of the reasons to look at these best practices are:

    1. Planning your project workspace helps you and new users find code, library dependencies, data and configuration files.
    2. Standard file structures makes future extensions to your product easier by allowing easier integrations with external libraries, IDEs etc.
    3. If your project files needs to be source control managed along with other projects in an organization, it needs to follow a standard structure to keep code structure consistent – which benefits from organization specific tools and processes around build, development, test and deployment that are usually designed based around the end use and release cycles for products developed within that organization.

    Steps to create your project workspace:

    • Structure your directories based on your project goals/ requirements
    • Set up a build environment to compile and package your code
    • Source control

    Structuring your directories

    Before you get to the stage of creating your project, you probably already have a set of requirements for the application you are building in your project. Based on those requirements you probably already have some idea about what categories of files you need to have for your project. You will need to organize your files in directories depending mainly on:

    • Category of files they contain. For example: data, config, application source code etc, and
    • How you want to want to package the project. For example source code versus compiled files.

    Since this website focuses on automation and on several java based technologies, let’s use a automation test harness project as an example. In this case, you will need at the very minimum directories for:

    Java source code

    There are two most common ways java code is placed within a single module java application. The first is to have a directory called src directly under the module root folder, and the second is to have a folder called java under which you have the src folder.


    You would also need a directory that holds all the libraries your source code depends on/ uses. The practice that almost always is followed is to have all the library jar files under a folder called lib under the module root.

    In some cases you might have multiple jar that contain different versions of the java classes in them. This can cause problems in the behavior of your app because there could be differences in the way the classloader loads these classes. As far as possible you should try to avoid this situation. But, when you can’t, one solution could be to have a endorsed directory that you specify as a java argument so these jars would have precedence. Even though the endorsed directory can be created anywhere, the most common location for it is under the lib directory.

    Configuration files

    If you want to change the behavior of your application based on how your end users would use it, you will most likely need a few configuration files. Configuration files are often represented as key value pairs, called simply as properties files, or as xml files. You can put these files under a config directory in the root folder.

    In some cases you might have to package some or all of your config files along with your java source code. An example of this is the GanttProject. In such a case, you might want to place these config files in the resources directory under the same directory that src is in.


    Once you start writing code for your application you would want to package the compiled code before running it. The common practice is to have the compiled classes in the classes directory. The classes directory almost always is placed under the same directory that src is in.

    Once you have compiled your classes you might want to jar it. The two most common locations to place the jar is under the classes directory or even better under a build directory that you place in your application root directory.

    Log files

    Log files written by your application can be placed in the log directory under your root directory.
    Finally let’s assume here that the root directory for your project is simply called testautomation. So, now your directory structure would look something like this –

        - build
        - config
        - java
            - src
            - resources
            - classes
            - test
        - lib
        - log

    Building your project

    Instead of entering all the steps to compile, package, run and test your application, you should script that as single commandline commands. One of the common ways to do this is by using ant or maven.


    To build your application using ant, you need to write a build.xml file that you place in your application root directory. For the above directory structure you could use the following build.xml to begin with.

    <project basedir="." name="Test Automation">
        <property name="src.dir" value="${basedir}/java/src"/>
        <property name="resources.dir" value="${basedir}/java/resources"/>
        <property name="classes.dir" value="${basedir}/java/classes/main"/>
        <property name="lib.dir" value="${basedir}/lib"/>
        <property name="build.dir" value="${basedir}/build"/>
        <property name="testautomation.jar" value="${build.dir}/testautomation.jar"/>
        <path id="testautomation.classpath">
            <file file="${testautomation.jar}"/>
            <fileset dir="${lib.dir}">
                <include name="*.jar" />
        <target name="clean" description="cleans build output">
            <delete dir="${classes.dir}" quiet="true" includeemptydirs="true"/>
            <delete dir="${build.dir}" quiet="true" includeemptydirs="true"/>
        <target name="resources">
            <copy todir="${classes.dir}">
                <fileset dir="${resources.dir}"/>
        <target name="build" depends="resources" description="sets up the environment for test execution">
            <mkdir dir="${classes.dir}"/>
            <mkdir dir="${build.dir}"/>
            <javac debug="true"
            <jar basedir="${classes.dir}" jarfile="${testautomation.jar}"/>
        <target name="run-example" description="run command-line example">
            <java classname="net.qaautomation.examples.${example}"

    Source control

    Once you setup your project and you want to continue development on it by either just yourself or along with others, its a good idea to use a source control management tool.The best people to talk to to figure out where to place your application source code is your release engineering team

    When you are checking in your project files in most cases you would not want to check in your compiled classes, logs or even the build files i.e. do not check in your classes, logs and build directories.

    If your application is a automation test harness, you should try to get it into the same location that the application it tests resides in. The advantage of doing this is that whenever project branches are created, your automation code would automatically branch too. Any automation code changes that you will need to make for the new project branch can now be made in the same location. When the application under test is ready for release, as it gets into the trunk, so will your automation code. This ensures your automation code to always stay compatible with the Application Under Test’s code. The only aspect to keep in mind here is that you would probably not want the application under test’s build and deploy scripts to package your automation code to be released into the production environments.

    Posted by Rahul Poonekar in : Integration

    2 responses to “Creating your Java project workspace”

    1. Deepa says:

      Hi Rahul,

      I am completely new to test automation and i found your details very helpful. But in my project we are using Maven as build tool. How to create build.xml for Maven? Also i just created the folder structure suggested above and downloaded Selenium 2. What are other other configs or intallables I need to have? I knew am asking very silly questions but as I am very new in setting up this. Your help is very much appreciated.


    2. Senthil says:

      Thanks for your inputs really helping lot to go ahead with my day to day tasks

    Leave a Reply

    Your email address will not be published. Required fields are marked *