Bug: unable to create instance of `IteratorTester`

[jbduncan]

Bug description

When I attempt to create an instance of com.google.common.collect.testing.IteratorTester from guava-testlib version 29-jre, I end up with the following compilation error message:

/path/to/IteratorTesterExampleTests.java:3: error: package com.google.common.collect.testing.AbstractIteratorTester does not exist
import com.google.common.collect.testing.AbstractIteratorTester.KnownOrder;
                                                               ^
/path/to/IteratorTesterExampleTests.java:26: error: cannot find symbol
            3, IteratorFeature.UNMODIFIABLE, Arrays.asList("a", "b", "c"), KnownOrder.KNOWN_ORDER) {
                                                                           ^
  symbol:   variable KnownOrder
  location: class IteratorTesterExampleTests

My workaround is to copy IteratorTester, AbstractIteratorTester and Helpers into my project.

How to reproduce

1. git clone https://github.com/jbduncan/iteratortester-compilation-bug.git
2. ./gradlew build

Possible fixes

• Make AbstractIteratorTester public and its constructor non-public, documenting that it's not intended to be extended
• Move KnownOrder into a separate file (breaking change)
• Make IteratorTester non-public, at the risk of making guava-testlib users except Guava itself not being able to use it anymore (breaking change)

[cpovirk]

Not at my computer, but will Java let you import it as IteratorTester.KnownOrder?

[jbduncan]

Aha, yes I can import KnownOrder if I use it as IteratorTester.KnownOrder! 🎉

But this only works if I use it inline like so:

new IteratorTester<String>(
    3, IteratorFeature.UNMODIFIABLE, Arrays.asList("a", "b", "c"), IteratorTester.KnownOrder.KNOWN_ORDER) {
  @Override
  protected Iterator<String> newTargetIterator() {
    return iterable.iterator();
  }
};

If I try the following, it fails to compile:

import com.google.common.collect.testing.IteratorTester.KnownOrder;

...

new IteratorTester<String>(
    3, IteratorFeature.UNMODIFIABLE, Arrays.asList("a", "b", "c"), KnownOrder.KNOWN_ORDER) {
  @Override
  protected Iterator<String> newTargetIterator() {
    return iterable.iterator();
  }
};

Specifically it fails with the following message:

/path/to/IteratorTesterExampleTests.java:5: error: import requires canonical name for KnownOrder
import com.google.common.collect.testing.IteratorTester.KnownOrder;

The second option - using it in an import ... - is what IntelliJ IDEA suggests to me, so I'm not sure at this stage if either Guava is inadvertently abusing Java syntax or if IntelliJ's the one that's buggy.

[jbduncan]

Ah sorry, actually IntelliJ suggests that I import com.google.common.collect.testing.AbstractIteratorTester.KnownOrder;, so the abstract base class rather than IteratorTester itself.

This seems to suggest more that it's an IntelliJ bug...

Thoughts?

[jbduncan]

Regardless, I think that IteratorTester's class javadoc could do with an example to show how to use the class properly so that problems like the one above are lessened. Any thoughts on this as well?

[cpovirk]

Yeah, this is all unfortunate. I'd be happy to look at a PR for Javadoc. Ideally we'll someday fix the API, but we'd have to think about how to do that without too much additional disruption and confusion.

[jbduncan]

Okay! I'm more than happy to provide a PR, but I don't yet know when I'll have the time to do it. I'll keep you posted.

[jbduncan]

@cpovirk I found the time this evening to raise a PR (#5272). :)

[jbduncan]

@cpovirk Thanks for merging it in, but I found a mistake in my example in the PR: it uses KnownOrder directly rather than IteratorTester.KnownOrder, so it doesn't compile. 🤦

So I've raised a new PR to fix that: #5276.

Sorry about that, and thanks in advance!