Orientation in Objects

getting started


Using JpdfUnit there are some dependencies which have to be set. By name there is a need to integrate JUnit, PDFBox and Log4j Project (Deprecated since 0.92). The tested versions of the dependencies are added to our distribution files which you can download here. Integrate the jars into your project now you are ready to write your own tests and to use the functionality of JpdfUnit.

howto work with JPdfUnit

1. download the java archives(jar)

JPdfUnit was developed with the following dependencies. You can download the actual versions of the dependencies following the links below.

Junit  (tested) JUnit
PDFBox  (tested) PDFBox
log4j  (tested)(Deprecated since 0.92) Log4j Project

2. integrate the jars into your own project

After downloading the three archives you have to integrate these archives into your project.

3. integration with Apache Maven

An alternative to integrate the jars manually is to use Apache Maven. To do this you can upload JPdfUnit and PDFBox to your own Maven repository or you can use the Maven repository hosted on the JPdfUnit website ( The following code shows an example of how to use the JPdfUnit Maven repository in your pom file:

	<description>Test project for JPdfUnit Maven repo.</description>


JPdfUnit integrates PDFBox as an PDF API with the JUnit framwork for the test of pdf documents so JPdfUnit is a high level api. It was designed for an easy access to the PDFBOX library without having to use it directly. For instance you can test the meta data of the pdf document like the author or the creation date or search for content via Strings, fragments of words or even regular expressions. Different simple ready-to-use assertions allow the user to compare the expected data to the concrete data of the pdf document. JPdfUnit tests one pdf document. Three typical usage scenarios of JPDFUnit are documented in the framework.

1. example

For a better understanding of JPdfUnit there is a simple example. It shows a typical basic test of embbeded text elements and some meta information. The document is a real life example a training curriculum of a Java service company. The examples and the pdf files also can be found in the sources of JPdfUnit.

public class GenerelDocumentTest extends DocumentTestCase {

	 * @param name
	public GenerelDocumentTest(String name) {

	protected DocumentDataSource getDataSource() {
		DocumentDataSource datasource = new PdfDataSource(
		return datasource;
	public void testAssertContentContainsText() {
         	//a pdf document could probably contain more information and text you expect
		assertContentContainsText("Naja,", TextSearchType.STARTSWITH);
				"[\\S+\\s+]+?OIO-Akademie[\\s+\\S+]+?", TextSearchType.REGEXP);

	public void testAssertDocumentInformation() {
		assertCreatorEquals("XEP 3.7.8 Client");


public class AllTests {

	public static Test suite(){
		TestSuite suite = new TestSuite();
		suite.addTest(new TestSuite(GenerelDocumentTest.class));
		return suite;

2. write your own tests

There are three posibilities to test with JPdfUnit. Either your Test could simply extend the DocumentTestCase class or you could work with the DocumentTester class of the framework. The second posibility is designed for the case that you can not inherit the DocumentTestCase class due to other dependencies i.e. jWebUnit. Third you can use JPdfUnit as a high level api for accesing documents.

2.1. extend the DocumentTestCase class

The easiest way to use jpdfunit is to make your test class extend the DocumentTestCase class. First you need to create a test class. DocumentTestCase extends the JUnit TestCase class. There is just one method which has to be implemented the getDataSource(). We hide the setup() and tearDown() mechanism and use it for the document handling (i.e. creating testing objects and closing the document for you). There is a template method to access the setup method. You have to overwrite the onSetup() method for your own setup. Following is a sample implementation:

public class OioTest extends DocumentTestCase {

    public OioTest(String name) {
    //get up your data source
    protected DocumentDataSourcet getDataSource() {
        DocumentDataSource datasource = new PdfDataSource("etc/testing-pdfs/DocumentEncryptionTest.pdf");
    return datasource;
    //test if the document is encrypted
    public void testAssertIsDocumentEncrypted(){

2.2. Do not extend the DocumentTestCase class

In order to use Jpdfunit you are not required to extend the DocumentTestCase class. You can also use the DocumentTester class which is the core element of JPdfUnit. The best practice is to override the standard JUnit setUp() method creating there a DocumentTester with your pdf as parameter for the constructor. After this inital step execute the desired operation on your pdf file. And close the document of your DocumentTester in the teardown() method. Following is a sample implementation:

public class AllTests {

        public static Test suite(){
        TestSuite suite = new TestSuite();
        suite.addTest(new TestSuite(PdfTesterEncryptionTest.class));
        return suite;

import junit.framework.TestCase; import de.oio.jpdfunit.DocumentTester; public class DocumentTesterEncryptionTest extends TestCase{

    //know you need a DocumentTester for testing the pdf document
    private DocumentTester tester;
    public DocumentTesterEncryptionTest(String name){
//you have decided to inherit another TestCase normally you have to overwrite the setup() now     protected void setUp() throws Exception {
    // creating a new DocumentTester via String parameter
        tester = return new DocumentTester("etc/testing-pdfs/DocumentEncryptionTest.pdf");
//you have decided to inherit another TestCase normally you have to overwrite the tearDown() now     protected void tearDown() throws Exception {
    //after finishing your tests you have to close the DocumentTester
    //test the encryption length of your pdf document
    public void testAssertEncryptionLenghthEquals(){

3. just use the DocumentTester class in a application

As promised here is the third possibility to use the framework. Therefore you have to create a DocumentTester in your Output class and work with the DocumentTester's Content and Document to work with the framework without using JUnit.

public class TesterWorks {

	private static DocumentTester tester = new DocumentTester("etc/testing-pdfs/DocumentEncryptionTest.pdf");
	private static DocumentTester myTester = new DocumentTester("etc/testing-pdfs/DocumentInformationTest.pdf");

	public static void main (String []args) throws Exception {
                 //using two tester in this example because one pdf is encrypted
		System.out.println("Is document encrypted? " + tester.getDocument().isDocumentEncrypted() );
                 //if the document is not encrypted you can access all meta data and content via the Content
                 //and Document interfaces of the DocumentTester
                 System.out.println("Page Count ? " + myTester.getDocument().countPages() );
                 //be good and close the documents after work



4. write your own assert methods

Finally there is the possibility to write own assert methods. So you have to work again with the DocumentTester and the interfaces Document and Content depending on your new assert method. Here is a method of the DocumentTester your own assert methods could look similar:

public void assertContentContainsText(String text, TextSearchType type) {
		"The testet pdf-document doesn't contain the expected parameter.",
		content.isTextContent(text, type));

Valid XHTML 1.0! Valid CSS! Desidned by CSS!