shaka-packager/packager/third_party/protobuf/java/compatibility_tests/README.md

Protobuf Java Compatibility Tests

This directory contains tests to ensure protobuf library is compatible with previously released versions.

Directory Layout

For each released protobuf version we are testing compatibility with, there is a sub-directory with the following layout (take v2.5.0 as an example):

• v2.5.0
  • test.sh
  • pom.xml
  • protos/ - unittest protos.
  • more_protos/ - unittest protos that import the ones in "protos".
  • tests/ - actual Java test classes.

The testing code is extracted from regular protobuf unittests by removing:

• tests that access package private methods/classes.
• tests that are known to be broken by an intended behavior change (e.g., we changed the parsing recursion limit from 64 to 100).
• all lite runtime tests.

It's also divided into 3 submodule with tests depending on more_protos and more_protos depending on protos. This way we can test scenarios where only part of the dependency is upgraded to the new version.

How to Run The Tests

We use a shell script to drive the test of different scenarios so the test will only run on unix-like environments. The script expects a few command line tools to be available on PATH: git, mvn, wget, grep, sed, java.

Before running the tests, make sure you have already built the protoc binary following the C++ installation instructions. The test scripts will use the built binary located at ${protobuf}/src/protoc.

To start a test, simply run the test.sh script in each version directory. For example:

$ v2.5.0/test.sh

For each version, the test script will test:

• only upgrading protos to the new version
• only upgrading more_protos to the new version

and see whether everything builds/runs fine. Both source compatibility and binary compatibility will be tested.