Guideline to Run Tests - marklogic/marklogic-contentpump GitHub Wiki

This is a guideline that helps you to run tests in MLCP. This article also includes the requirement to verify your contributions to submit a pull request.

Test Environment

MLCP tests require a running MarkLogic Server instance. By default, MLCP runs tests under these MarkLogic configurations:

  • MarkLogic Server with the same version of MLCP runs on localhost.
  • mlcp-unittest-db database will be created.
  • mlcp-unittest-db database uses Modules database as the module database.
  • An XDBC server mlcp-unittest-dbAppServer will be created with port 5276.
  • Username/password admin/admin will be used to run tests.

You can customize some of these settings with Configurable Test Parameters.

MLCP tests will make the following setups:

  • Enable triple index on mlcp-unittest-db database.
  • Enable collection lexicon on mlcp-unittest-db database.
  • Create range element indexes on mlcp-unittest-db database.
  • Create temporal axes on mlcp-unittest-db database.
  • Create temporal collections on mlcp-unittest-db database.
  • Create mlcp-unittest-copy-db database with port 6276 by default for MLCP COPY unit tests. If the user specifies a custom CopyDst database name, MLCP will also check the existence of the database and create it if necessary.

If a customized test database has been specified, the above setups on the default database will be applied. MLCP won't clean up these setups after the unit tests are finished.

How to Run

To run tests in MLCP, from marklogic-contentpump/ root directory, run command

$ mvn test

Things to note:

  • Maven builds the product before "test" phase.

Configurable Test Parameters

You can customize your test environment settings by specifying additional parameters to the test command. All the below parameters are optional. Default values will be used if not specified.

Parameter Type Default Usage Example Description
test string Not used -Dtest=TestImportDocs Specify the test to run. Read more from Maven Surefile Plugin
skipTests boolean false -DskipTests=false Whether tests should be skipped
testDb string mlcp-unittest-db -DtestDb=Documents The database that tests will use
testDbPort string 5276 -DtestDbPort=5276 The port that tests will use to talk to MarkLogic Server
copyDb string mlcp-unittest-copy-db -DtestCopyDst=mlcp-unittest-copy-db The database that tests for COPY command will copy to
copyDbPort string 6276 -DcopyDbPort=6276 The port that tests for COPY will use to talk to MarkLogic Server
testOutputPath string /tmp/mlcpout -DtestOutputPath=/tmp/mlcpout The directory path to save tests output

Verify Your Changes

If you make changes to MLCP, you should verify that your change doesn't introduce any issues by running and passing MLCP unit tests.

CURRENTLY, the bottom line for the project maintainers to take a pull request of your contributions to MLCP is to pass all MLCP tests. Pull requests with failing tests won't be accepted. The unit tests included in MLCP are only a minimum set of all the tests we have for the products. They are only designed for a sanity check.

More contribution policies are under discussion.

Troubleshooting

You can enable debug level log messages to see detailed debugging information about what mlcp is doing.

For mlcp 9 versions below 9.0.13.7 and mlcp 10 versions below 10.0.8.2, to enable debug logging:

  1. Edit the file marklogic-contentpump/conf/log4j.properties.
  2. In log4j.properties, set the properties log4j.logger.com.marklogic.mapreduce and log4j.logger.com.marklogic.contentpump to DEBUG. For example, include the following:
log4j.logger.com.marklogic.mapreduce=DEBUG
log4j.logger.com.marklogic.contentpump=DEBUG

You may find these property settings are already at the end of log4j.properties, but commented out. Remove the leading # to enable them.

In 9.0.13.7 and 10.0.8.2, we migrated log4j to log4j2 due to security vulnerabilities. For mlcp 9 versions 9.0.13.7 and after, and 10 versions 10.0.8.2 and after:

  1. Edit the file marklogic-contentpump/conf/log4j2.xml.
  2. In log4j2.xml, set the level to DEBUG for logger com.marklogic.mapreduce and com.marklogic.contentpump. For example, include the following:
<Logger name="com.marklogic.mapreduce" level="DEBUG" additivity="false">
 <AppenderRef ref="Console"/>
</Logger>
<Logger name="com.marklogic.contentpump" level="DEBUG" additivity="false">
 <AppenderRef ref="Console"/>
</Logger>

You may find these property settings are already in log4j2.xml, but commented out. Remove the leading <!-- and --> to enable them.

⚠️ **GitHub.com Fallback** ⚠️