Checkout the getting started section to setup the test environment correctly.
Checkout the sub-component testing section before diving into prop matching.
In this article, we will drill a bit deeper and explore TestSpecs as a way to test individual props of those components, even if we don't know all of them.
Composability is one of the big strengths Litho has to offer. It allows you to encapsulate your logic in small components and compose them together effortlessly into larger ones. But despite all good efforts, sometimes there is no clear dividing line and your component may grow beyond its original scope.
Having more complex components shouldn't prevent you from using them confidently. That's why we have a set of powerful APIs to test your components no matter the size.
For this example, let's consider this LayoutSpec:
When we look at the props of our
ComplexComponent, we see a lot of opaque
objects that we may have trouble getting ahold of for our tests.
might be something we obtain through some dependency injection mechanism. A
DraweeController is an implementation detail we shouldn't have to worry about
for ensuring that the component tree has the right shape.
However, if you remember the
SubComponent.of API, we need to specify all
non-optional props for it to succeed. Let's see what this would look like:
As always, we create a standard JUnit test suite and run it with a
RobolectricTestRunner-compatible implementation like
For the purpose of this article, we assume that we have a
that contains our
FeedItemComponent contains the logic
for populating our complex props which we want to verify.
Sadly, this test fails with this error message:
But what if we can't provide these props in our tests? Or if we don't want to test implementation details like the image loading controller?
We could simply choose not to test any props at all and decide to verify only the presence of our component.
Clearly, having this test is better than nothing. In the same way that having some Starbucks coffee after a cross-Atlantic flight is better than no coffee at all ... but I digress.
What if there was a way to match just some of our props?
Props Matching with
TestSpecs allow you to match against exactly those props that you choose to test. Just as LayoutSpecs and MountSpecs, TestSpecs make use of the powerful annotation processing mechanism Java offers and generate code for you.
We start by creating a new class as part of our testing project and link to the original spec we want to generate our TestSpec for.
There are a few things to note here:
- The class you reference in
@TestSpecmust be a LayoutSpec or MountSpec.
- You must link to the Spec and not the generated component, e.g.
- In contrast to other specs, TestSpecs are generated from an interface, not a class.
- The interface must be empty, i.e. cannot have any members.
- By convention, you prefix your TestSpec with
Test, followed by the original spec name.
And that's it. Those two lines are enough to generate us a powerful matcher that we can use in our tests.
Now that we have our TestSpec generated, let's put it into use. Where normal
components have a
create function, test specs come with a
It does take the same props as the underlying component but, and this won't come
as a surprise, allows omitting non-optional props.
Obviously, this outrageous omission of puppies couldn't possibly pass the test run and will fail with a helpful error message:
Here we can see a brief overview of the hierarchy we were matching against and the matcher that failed.
But wait, there's more! Instead of just matching against partial props, you can also provide hamcrest matchers in any place that accepts concrete values. For props that take resource types, you can make use of all the same matchers you find in regular components.
There is one type of prop that requires some special treatment: components. While we could just match against child components via normal equality (and there is indeed support for this), it is not particularly helpful. We rarely know what exact instance of a component is passed down to the props and we face many of the same problems we discussed before: The props of the Component may not be known in full or perhaps we don't want to provide them all.
The solution to this is obvious: We match matchers! For any prop that takes a Component, the TestSpec generates a matcher that takes another matcher. This allows for declarative matching against entire trees of components.
For our example, let's suppose that our
FeedItemComponent wraps the
ComplexComponent in a
TestCard we use to declare our hierarchy here. The
package comes with TestSpecs for all standard Litho widgets.
If you use gradle, this should Just Work™ and shouldn't require any additional setup.
With Buck or Blaze/Bazel, however, you may need some additional configuration for the annotation processing step to work.
In order to save you copy-pasting boilerplate all over your project, it is
recommended keep a rule definition like this in a well-known place
//tools/build_defs/android/litho_testspec.bzl). You would obviously have to adjust
the library paths to the corresponding targets in your code base.
In the definitions for your test suite, you can then create a separate target for your test specs:
This ensures that test specs are processed by the dedicated
Create a TestSpec for your LayoutSpec or MountSpec.
Use the generated test matcher in your suite.