feature: WIP: Subject code generator, fixes #612

[astubbs]

An implementation of #612 Consider auto-generating assertThat and subject factory for custom subjects

Generates the bare bones boiler plate subject for later extension.

Needs several usability

Issue with this, is if you use the pattern of extending the generated classes - the accessor methods return itself, not the class you've extended. Still super useful to bootstrap many model classes. There may be a way around this - need to think about it. Otherwise, Roaster also allows modifying existing classes - so could try experimenting with mutating existing classes, instead of overwriting them - this will preserve the custom assertion methods added to the class after it's first generated.

• Clean up
• Merging everything to be in line with the other models (java version, deps etc)
• Improvements to make it practically accessible.
• Template the javadoc statements or other large text bits or code, larger segment templating getting hard to read (no parameter names e.g. just %s's)
• Some basic refactoring.
• Add options for targets - like entire package contents as opposed to single classes.
• Add a tag annotation to use for targets.
• Generate basic usefull assertions for primitives e.g. employee#hasName().
• Wrap in a maven plugin - otherwise, it can just be run on a beforeSuite step in unit tests, but that's slow to run it every time.
• Optional Recursive generation of Subjects so you don’t have to register them all

Features (done):

• Dog foods - uses it’s own bootstrapped Subjects to test itself
• Single entry point for all Managed subjects
• Template generation for easy incorporation of custom Subjects in your managed source control
• Ignoring white space and line endings string Subject
• Various ways to specify classes under test for generation
• Shade other module classes like java.* classes (UUID etc)
• Several standard assertion strategies
• Chain assertion strategy
• Detection of existing user managed Subject - doesn't regenerate
• Support for legacy non bean compliant objects like Kafka's ConsumerRecord

More (done):

• Optional Recursive generation of Subjects so you don’t have to register them all - going into external modules (i.e. java's UUID, ZonedDateTime etc)
• Automatic shading of classes who's package is contained in an existing module already (e.g. can't put java.util.UUID's subject into same package java.util)
• Maven plugin

More (done):

• Collections, maps etc generic types are read And used in assertions ie assert.map.containsKey(MyKey key)
• Customisable extension points for base subjects (like list and map) which will apply to all types in generated tree (where generated entry points are used)

[google-cla]

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project (if not, look below for help). Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://cla.developers.google.com/ to sign.

Once you've signed (or fixed any issues), please reply here with @googlebot I signed it! and we'll verify it.

---

What to do if you already signed the CLA

Individual signers

• It's possible we don't have your GitHub username or you're using a different email address on your commit. Check your existing CLA data and verify that your email is set on your git commits.

Corporate signers

• Your company has a Point of Contact who decides which employees are authorized to participate. Ask your POC to be added to the group of authorized contributors. If you don't know who your Point of Contact is, direct the Google project maintainer to go/cla#troubleshoot (Public version).
• The email used to register you as an authorized contributor must be the email used for the Git commit. Check your existing CLA data and verify that your email is set on your git commits.
• The email used to register you as an authorized contributor must also be attached to your GitHub account.

ℹ️ Googlers: Go here for more info.

[google-cla]

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project (if not, look below for help). Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://cla.developers.google.com/ to sign.

Once you've signed (or fixed any issues), please reply here with @googlebot I signed it! and we'll verify it.

---

What to do if you already signed the CLA

Individual signers

• It's possible we don't have your GitHub username or you're using a different email address on your commit. Check your existing CLA data and verify that your email is set on your git commits.

Corporate signers

• Your company has a Point of Contact who decides which employees are authorized to participate. Ask your POC to be added to the group of authorized contributors. If you don't know who your Point of Contact is, direct the Google project maintainer to go/cla#troubleshoot (Public version).
• The email used to register you as an authorized contributor must be the email used for the Git commit. Check your existing CLA data and verify that your email is set on your git commits.
• The email used to register you as an authorized contributor must also be attached to your GitHub account.

ℹ️ Googlers: Go here for more info.

[google-cla]

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project (if not, look below for help). Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://cla.developers.google.com/ to sign.

Once you've signed (or fixed any issues), please reply here with @googlebot I signed it! and we'll verify it.

---

What to do if you already signed the CLA

Individual signers

• It's possible we don't have your GitHub username or you're using a different email address on your commit. Check your existing CLA data and verify that your email is set on your git commits.

Corporate signers

• Your company has a Point of Contact who decides which employees are authorized to participate. Ask your POC to be added to the group of authorized contributors. If you don't know who your Point of Contact is, direct the Google project maintainer to go/cla#troubleshoot (Public version).
• The email used to register you as an authorized contributor must be the email used for the Git commit. Check your existing CLA data and verify that your email is set on your git commits.
• The email used to register you as an authorized contributor must also be attached to your GitHub account.

ℹ️ Googlers: Go here for more info.

[astubbs]

@googlebot I signed it!

[astubbs]

FYI, needs more work of course, but I know have a 3 class system,

• a parent that is generated and has all the new stuff that'll evolve over a time
• a generated bare bones class that extents parent which use can copy into source control and add custom stuff to
• child which extends user's class and manages the access points (not sure this is needed, but it keeps the generated part of the user class smaller

All generated assertion entry points get collected into a ManagedTruth class (sample at the bottom here).

And have started experimenting with some basic test generation. It's all generated except for:

	void hasCustomAdvancedUserWrttenTest(){
		// ...
	}

package io.confluent.parallelconsumer.state;

import com.google.common.truth.BooleanSubject;
import com.google.common.truth.FailureMetadata;
import com.google.common.truth.IntegerSubject;
import com.google.common.truth.Subject;

/**
 * Truth Subject for the {@link WorkContainer}.
 * 
 * Note that this class is generated / managed, and will change over time. So
 * any changes you might make will be overwritten.
 * 
 * @see WorkContainer
 * @see WorkContainerSubject
 * @see WorkContainerChildSubject
 */
public class WorkContainerParentSubject extends Subject {

	protected final WorkContainer actual;

	protected WorkContainerParentSubject(FailureMetadata failureMetadata,
			io.confluent.parallelconsumer.state.WorkContainer actual) {
		super(failureMetadata, actual);
		this.actual = actual;
	}

	public IntegerSubject hasepoch() {
		return check("epoch").that(actual.getEpoch());
	}

	public BooleanSubject hasinFlight() {
		return check("inFlight").that(actual.isNotInFlight());
	}

	public IntegerSubject hasnumberOfFailedAttempts() {
		return check("numberOfFailedAttempts").that(actual.getNumberOfFailedAttempts());
	}
}

package io.confluent.parallelconsumer.state;

import io.confluent.parallelconsumer.state.WorkContainerParentSubject;
import com.google.common.truth.FailureMetadata;

/**
 * Optionally move this class into source control, and add your custom
 * assertions here.
 * 
 * @see WorkContainerParentSubject
 */
public class WorkContainerSubject extends WorkContainerParentSubject {

	protected WorkContainerSubject(FailureMetadata failureMetadata,
			io.confluent.parallelconsumer.state.WorkContainer actual) {
		super(failureMetadata, actual);
	}

	/**
	 * Returns an assertion builder for a {@link WorkContainer} class.
	 */
	public static Factory<WorkContainerSubject, WorkContainer> workContainers() {
		return WorkContainerSubject::new;
	}
	
	void hasCustomAdvancedUserWrttenTest(){
		// ...
	}
}

package io.confluent.parallelconsumer.state;

import io.confluent.parallelconsumer.state.WorkContainerSubject;
import static io.confluent.parallelconsumer.state.WorkContainerSubject.*;
import com.google.common.truth.Truth;

/**
 * Entry point for assertions for @{WorkContainer}. Import the static accessor
 * methods from this class and use them. Combines the generated code from
 * {@WorkContainerParentSubject}and the user code from
 * {@io.confluent.parallelconsumer.state.WorkContainerSubject}.
 * 
 * @see io.confluent.parallelconsumer.state.WorkContainer
 * @see io.confluent.parallelconsumer.state.WorkContainerSubject
 * @see WorkContainerParentSubject
 */
public class WorkContainerChildSubject extends WorkContainerSubject {

	/**
	 * Entry point for {@link WorkContainer} assertions.
	 */
	public static WorkContainerSubject assertThat(io.confluent.parallelconsumer.state.WorkContainer actual) {
		return Truth.assertAbout(workContainers()).that(actual);
	}

	/**
	 * Convenience entry point for {@link WorkContainer} assertions when being mixed
	 * with other "assertThat" assertion libraries.
	 * 
	 * @see #assertThat
	 */
	public static WorkContainerSubject assertTruth(io.confluent.parallelconsumer.state.WorkContainer actual) {
		return assertThat(actual);
	}
}

package io.confluent.parallelconsumer.truth;

import io.confluent.parallelconsumer.state.WorkContainerSubject;
import static io.confluent.parallelconsumer.state.WorkContainerSubject.*;
import com.google.common.truth.Truth;
import io.confluent.parallelconsumer.model.CommitHistorySubject;
import static io.confluent.parallelconsumer.model.CommitHistorySubject.*;
import io.confluent.parallelconsumer.offsets.EncodedOffsetPairSubject;
import static io.confluent.parallelconsumer.offsets.EncodedOffsetPairSubject.*;

/**
 * Single point of access for all managed Subjects.
 */
public class ManagedTruth {

	/**
	 * Entry point for {@link WorkContainer} assertions.
	 */
	public static WorkContainerSubject assertThat(io.confluent.parallelconsumer.state.WorkContainer actual) {
		return Truth.assertAbout(workContainers()).that(actual);
	}

	/**
	 * Convenience entry point for {@link WorkContainer} assertions when being mixed
	 * with other "assertThat" assertion libraries.
	 * 
	 * @see #assertThat
	 */
	public static WorkContainerSubject assertTruth(io.confluent.parallelconsumer.state.WorkContainer actual) {
		return assertThat(actual);
	}

	/**
	 * Entry point for {@link CommitHistory} assertions.
	 */
	public static CommitHistorySubject assertThat(io.confluent.parallelconsumer.model.CommitHistory actual) {
		return Truth.assertAbout(commitHistories()).that(actual);
	}

	/**
	 * Convenience entry point for {@link CommitHistory} assertions when being mixed
	 * with other "assertThat" assertion libraries.
	 * 
	 * @see #assertThat
	 */
	public static CommitHistorySubject assertTruth(io.confluent.parallelconsumer.model.CommitHistory actual) {
		return assertThat(actual);
	}

	/**
	 * Entry point for {@link EncodedOffsetPair} assertions.
	 */
	public static EncodedOffsetPairSubject assertThat(io.confluent.parallelconsumer.offsets.EncodedOffsetPair actual) {
		return Truth.assertAbout(encodedOffsetPairs()).that(actual);
	}

	/**
	 * Convenience entry point for {@link EncodedOffsetPair} assertions when being
	 * mixed with other "assertThat" assertion libraries.
	 * 
	 * @see #assertThat
	 */
	public static EncodedOffsetPairSubject assertTruth(io.confluent.parallelconsumer.offsets.EncodedOffsetPair actual) {
		return assertThat(actual);
	}
}

[astubbs]

Ok, it's mostly ready to look at now. I'm at my personal MVP and will start using it in my projects.

[astubbs]

rename from generate verb (as it doesnt yet), to something like 'add'

[astubbs]

adopt project naming style

[astubbs]

need to make sure test suite works as a whole

[astubbs]

Converted back to draft. Will mark ready again when:
[ ] clean up done
[x] collections customisation entry points done
[ ] project aligned
[ ] when I get a green light that this could actually get merged one day

[astubbs]

Hi @cpovirk , is it possible to get CI turned on for this PR? Or am I barking up the wrong tree here.. :)

[astubbs]

FYI, this is what some of the generated output looks like: https://github.com/astubbs/truth/blob/generator/extensions/generator/src/test/resources/expected/MyEmployeeParentSubject.java.txt

[astubbs]

heya @cpovirk , or anyone out there - if I could get an indication if there is any interest in merging this? Otherwise, I'll put effort into releasing it myself as a seperate project. But would rather not double up.
Cheers ❤️

[cpovirk]

Sorry, we keep saying that we need to write down the meanings of our priority labels, but we keep not doing so. "P3" == "not scheduled," so I would be happy to see such a thing released separately so that it exists and we can point people to it, rather than having it wait here indefinitely.

[astubbs]

Thanks Chris! Ok sweet as - shouldn't be too much work to migrate. Just the publishing part is a PITA :)
I'll clean it up as I've indicated, massage the API a bit more then release it. I'll post back here when it's ready - would still love even the most mildest of reviews then with suggestions or guidance on how you'd like to see it work or evolve.

[astubbs]

Ok @cpovirk - initial refactored version is here: https://github.com/astubbs/truth-generator
Lots left to do before publishing to repo1, but the plugin works for my needs atm. Will post back here again when 0.1 is available in repo1. But for now it can be installed locally and used (though that makes it unusable for actual projects, but people can try it out on their own stuff).

[astubbs]

The plugin is now available in a couple of Maven repositories (but not repo1 yet), and the README has been updated with feature list and examples. See the README for details.