ETLUnit 3.9.6

Draft in Progress

This document is a draft and is under development.

Description

Run one or more ETLUnit tests.

Much of what is presented here is laid out much more succinctly on the Test Specification Reference page.

Simplest Example

test alone runs all tests in the project.

test

test (or te) followed by a string identifying what test(s) to run.

e.g.,

test mytest

will run all the tests in any test class with the string "mytest" in its name.

The argument is generally, but not always (look at the tag syntax) case insensitive.

Types of Tests

suites

Runs all tests in all classes annotated with @JoinSuite, with a matching suite name.

classMethods

Four types
1. Package
2. Class
3. Method
4. Operation
The first three run test methods.
The last runs only the named operation.

properties

Runs all tests that match the operation and its value.

compound

Combine any of the other types using an available operator.
The operators:
1. or
2. and
3. eor
4. not
It is not recommended to use these on multiple levels. Since they are binary only, you will have to nest them if you want to use more than one operator. In fact, in general, they work best when both operands are of the same type.

Special Characters in the `test` Command Argument

Symbol	Where and How Used
`%`	Percent. Precedes a string that represents all or part of a package name. Unmodified, it will cause every test method in every class in every matching package to run. te %product_alias The above will run all tests in all classes in all packages with the string "`product_alias`" in their name.
`@`	At symbol. Precedes a string that represents part of a class name. Unmodified, it will cause every test method in every matching class to run. te @gap_bucket The above will run all tests in all classes with the string "`gap_ticket`" in their name.
`#`	Number sign, pound sign, or hash. Precedes a string that represents part of a method name. Unmodified, it will cause every matching test method to run. te #columnsloadinorder_bucket The above will run all tests with the string "`columnsloadinorder_bucket`" in their name.
`\|`	Pipe. Place at beginning or end of a package name, class name or method name. When placed at the beginning, the first character after the pipe symbol must be the first character in the name. test #\|columns The above will run all test methods that begin with "`columns`." A test method beginning with "`loadcolumns`" will not match. When placed at the end, the last character before the pipe symbol must be the last character in the name. test @reagg\| The above will run all tests in every test class with a name ending with "`reagg`." A test class ending with "`reagg_wkf`" will not match.
`$`	Dollar sign. Precedes the name of an operation to run. It will run the specified operation, not the entire enclosing test method. The name of the operation must be spelled out in full. If you try to abbreviate the "stage" operation to "stg," for instance, you will not see an error, the test will run, and the CLI will show that it passed. But in fact the stage operation did not run at all. To be redundant, the operation name must be spelled out in full. Usually used in conjunction with another classMethods specifier. te @load_plant_holiday_comp_change$stage The above will run only the `stage` operations in every test class with the string "`load_plant_holiday_comp_change`" in its name.
`<,>`	Angle brackets. Encloses tag information. Reruns tests you have already run from the CLI, based on tag names and qualifiers. If the comma is present, it separates a tag name from a tag qualifier (`all, success, fail, error or failError`). Tag qualifiers are case sensitive. tag t1 te @assert_samples.assert_with_columns_ii te <t1,error> The above will create a tag named `t1` as soon as you run the first `test` command. The second `test` command reruns the test, but only any tests that ended in error.
`[,]`	Square brackets. Encloses suite information. Unmodified, It will run every method in every class annotated with `@JoinSuite` and this suite name. Partial suite name will not be recognized. Comma separates multiple suite names. If more than one suite name is provided, tests in classes annotated with all suites in the list will be run. te [fact,agg,bucket_v2] The above runs all tests in all classes that have all three named tags, `fact`, `agg` and `bucket_v2`.
`{:,}`	Curly braces. Encloses property information. Unmodified, It will run every method that that has the provided property. Comma separates multiple properties. If more than one property is provided, tests that have all properties and corresponding values in the list will be run, as long as every property in the list is in the same operation. te {source-file: 'MONTHSUMMY'} The above will run all tests with the property `source-file`, where its assigned value contains the string '`MONTHSUMMY`.' There is no way to limit the test selection to filter out, for instance, the following: source-file: '`QTQ_MONTHSUMMY_AGG`.'

Go to top

Rules

The two commands test and te are synonyms. They are interchangeable.
The test command runs one or more ETLUnit tests.
The test(s) being run will be one of two types:

1. A test method
2. A test operation

A test command may run a single test or several tests based on the arguments given to the command.
Combining tests without operators
- In the case of the classMethods type of test, you may combine the tests in the single test command's argument without using any operators. The effect is that tests that fall in the intersection of all the provided classMethod types will be run. If one of the classMethod types is an operation, then only the named operation will be run. Otherwise test methods will be run.
- %packagName@className#methodName$operatorName is a legal test argument.
Combining tests with operators
- The following test types cannot be combined with one another without an operator:
  - classMethods
  - Suites
  - Operations
  - Tags
- Available operators
  - or - - AGGREGATION - - Runs all tests contained in EITHER the set on the left OR the set on the right, or BOTH.
  - and - - INTERSECTION - - Runs all tests contained in BOTH the set on the left AND the set on the right.
  - eor - - EXCLUSIVE DISJUNCTION - - All tests from EITHER the set on the left OR the set on the right but NOT BOTH.
  - not - - FILTRATION - - All tests from set on left FILTERED BY the set on the right. (The set on the right is SUBTRACTED FROM the set on the left.)
- You cannot join three or more expressions with logical operators on the same level.
  - "a and b and c" is not legal.
  - You can accomplish what you were trying to do, but by using binary expressions.
  - "(a and b) and c" is legal.

The following will run all the test methods in every test class with the text 'myTestClass' in its name:

test @myTestClass

The following will run all the test methods in every test class with a name that ends with 'conv:'

test @conv|

The following will run all the stage operations in every test class that contains the text "ConvReplete" in its name:

test @ConvReplete$stage

The following will run all test methods in every package with product_alias in its name:

test %product_alias

The following will run all test methods in every package with "manufacturer" in its name, as long as the methods reside in a test class that begins with "replicate:"

test %manufacturer@|replicate

The following will run all test methods with "studentNumber" in its name, as long as it resides in a test class with "college_center" in its name, which resides in a package with "epi" in its name.

test %epi@college_center#studentNumber

The following will run the same tests, but only the stage operation in each. This will include stage operations in any @BeforeTest method.

test %epi@college_center#studentNumber$stage

The following combines test types by using operators. The test methods that run will be those with "sql" in their name, residing in classes annotated with @JoinSuite(orig) and residing in a package with "assert_samples" in its name:

test (%assert_samples and [orig]) and #sql

If a test has a syntax error, such as a missing comma to separate properties of an operation, the test may fail to run, silently. You will need to find the syntax error manually and by trial and error.

The method stageDataFile() has a syntax error. There is no comma to separate the stage operation's two properties.

assert_with_columns.etlunit

@Description( description: [

'Shows how to ignore columns on the assert'

])

@Database(id: 'edw')

class assert_with_columns {

@BeforeTest

stageDataFile()

{

stage(

source: 'DATA_FILE'

target-table: 'TEST_TABLE'

);

}

@Test

allColumns(){

// full assert - all columns considered

assert(

source-table: 'TEST_TABLE',

target: 'DATA_FILE'

);

}

When the test is run, the test is not run.

userme > te @assert_with_columns|#|allcolumns|
Processing [0] tests
Tests run: 0, Time elapsed: 00.123 sec

When I correct my syntax error and rerun the test, ...

assert_with_columns.etlunit

...

@BeforeTest

stageDataFile()

{

stage(

source: 'DATA_FILE',

target-table: 'TEST_TABLE'

);

}

...

I see the normal feedback on the command line.

userme > te @assert_with_columns|#|allcolumns|
Processing [1] tests
class assert_samples.assert_with_columns   ---------------------------------------
1/1        .allColumns
  Passed                                                                      P[1]
Tests run: 1, Successes: 1, Time elapsed: 00.927 sec

Go to top

Run ETLUnit test through Maven 'test' target

Do this from your Windows or *nix shell, in the root of your ETLUnit project.
Use the same syntax after the equals sign that you would in ClamShell.
If you employ the pipe symbol ( "|" ) you will need to enclose the test command after the equals sign with double quotes.
Some examples:

mvn test -Detlunit-test=%myPackageName

mvn test -Detlunit-test=@myClassName

mvn test -Detlunit-test=#myMethodName

mvn test -Detlunit-test=%myPackageName@myClassName#myMethodName

mvn test -Detlunit-test="%myPackageName@myClassName#|myMethodName|"

Go to top

References

Test Specification Reference

test Command

test Command

Description

Simplest Example

Types of Tests

suites

classMethods

properties

tags

compound

Special Characters in the test Command Argument

Rules

Run ETLUnit test through Maven 'test' target

References

Special Characters in the `test` Command Argument