# AntUnit Ant Library

## Introduction

This is a library of Ant tasks that support writing tests for tasks using build files instead of JUnit.

## Requirements

The current version requires Ant 1.8.1 or later.

## Where is it?

The source code for the library lives in the ant-antlibs-antunit git repository - https://gitbox.apache.org/repos/asf/ant-antlibs-antunit.git.

## Installation

If you are building this from sources, run the antlib target and you'll get a file `ant-antunit.jar`.

There are several ways to use the tasks:

- The traditional way:

                <taskdef
                  resource="org/apache/ant/antunit/antlib.xml">
                  <classpath>
                    <pathelement location="YOUR-PATH-TO/ant-antunit.jar"/>
                  </classpath>
                </taskdef>

  With this you can use the tasks like plain Ant tasks, they'll live in the default namespace. I.e. if you can run <exec> without any namespace prefix, you can do so for <antunit> as well.
- Similar, but assigning a namespace URI

                <taskdef
                  uri="antlib:org.apache.ant.antunit"
                  resource="org/apache/ant/antunit/antlib.xml">
                  <classpath>
                    <pathelement location="YOUR-PATH-TO/ant-antunit.jar"/>
                  </classpath>
                </taskdef>

  This puts you task into a separate namespace than Ant's namespace. You would use the tasks like

                <project
                  xmlns:au="antlib:org.apache.ant.antunit"
                  xmlns="antlib:org.apache.tools.ant">
                  ...
                  <au:assertTrue>
                    <equals arg1="1" arg2="2"/>
                  </au:assertTrue>

  or a variation thereof.
- Using Ant's autodiscovery. Place `ant-antunit.jar` into a directory and use `ant -lib DIR-CONTAINING-THE-JAR` or copy it into `ANT_HOME/lib` - and then in your build file, simply declare the namespace on the `project` tag:

                <project
                  xmlns:au="antlib:org.apache.ant.antunit"
                  xmlns="antlib:org.apache.tools.ant">

  And all tasks of this library will automatically be available in the `au` namespace without any `taskdef`.

## Tasks and Types

- antunit - run unit tests, the tests are defined using build files that contain targets which follow a certain naming convention. This task borrows a lot of ideas from JUnit 3 and the junit task.
- assertTrue - asserts a condition and throws a custom BuildException if the assertion fails.
- more assertions - useful specialized versions of assertTrue.
- expectfailure - a task container useful for tests that assert build failures.
- logcontent - an Ant Resource that contains the log output of an AntUnit test.