TestKit and Plugins

I’m wondering about writing tests for custom Gradle plugins with the Gradle TestKit. The result of the code used in the build.gradle file behaves differently, depending on how you apply plugins.

Why does this work:
plugins {id 'mycustomplugin'}

but this does not:
apply plugin: 'mycustomplugin'

The latter fails with Plugin with id 'mycustomplugin' not found. What is the reason for that behavior?

The notation plugins { id 'mycustomplugin'} only works if you inject the classpath with GradleRunner.withPluginClasspath(Iterable<? extends File> classpath). See Javadocs for more information. Using the method requires a target Gradle version >= 2.8.

The notation apply plugin: 'mycustomplugin' only works if you provide the plugin classpath via buildscript.dependencies.classpath. This is required if you need to test your plugin code with a target Gradle version < 2.8.

The user guide on TestKit describes both methods in detail.

Thank you. I must have missed that part in the documentation.