Provide better diagnostics when a descriptor is missing a property required by the snippet template

[FloHin]

Background: I removed some method calls to "description()" to better debug my Rest tests, big mistake.

Now I understand the exception, but I needed to debug it, to understand that not the "description" of my entity was meant, but that "FieldDescriptor for path '$my_variable_name' has no description"

UseCase: As a developer, I want the exception to show me what field exactly is meant.

I understand that this is not a "bug report", but merely a minor proposal to improve "developer happiness", as it took me really a long time to figure out what was wrong

Reproduce:

Instead of

...
fieldWithPath(prefix + "input_data_type").type(JsonFieldType.STRING).description("DataType for input data")
...

forget the description

...
fieldWithPath(prefix + "input_data_type").type(JsonFieldType.STRING)
...

Exception:

No key, method or field with name 'description' on line 7
org.springframework.restdocs.mustache.MustacheException$Context: No key, method or field with name 'description' on line 7
	at org.springframework.restdocs.mustache.Mustache$VariableSegment.execute(Mustache.java:789)
	at org.springframework.restdocs.mustache.Template$1.execute(Template.java:131)
	at org.springframework.restdocs.mustache.Template$1.execute(Template.java:124)
	at org.springframework.restdocs.mustache.Template$Fragment.execute(Template.java:59)
	at org.springframework.restdocs.templates.mustache.AsciidoctorTableCellContentLambda.execute(AsciidoctorTableCellContentLambda.java:36)
	at org.springframework.restdocs.mustache.Mustache$SectionSegment.execute(Mustache.java:856)
	at org.springframework.restdocs.mustache.Mustache$BlockSegment.executeSegs(Mustache.java:827)
	at org.springframework.restdocs.mustache.Mustache$SectionSegment.execute(Mustache.java:848)
	at org.springframework.restdocs.mustache.Template.executeSegs(Template.java:114)
	at org.springframework.restdocs.mustache.Template.execute(Template.java:91)
	at org.springframework.restdocs.mustache.Template.execute(Template.java:82)
	at org.springframework.restdocs.templates.mustache.MustacheTemplate.render(MustacheTemplate.java:62)
	at org.springframework.restdocs.snippet.TemplatedSnippet.document(TemplatedSnippet.java:82)
	at org.springframework.restdocs.generate.RestDocumentationGenerator.handle(RestDocumentationGenerator.java:191)
	at org.springframework.restdocs.mockmvc.RestDocumentationResultHandler.handle(RestDocumentationResultHandler.java:52)
	at org.springframework.test.web.servlet.MockMvc$1.andDo(MockMvc.java:201)
	at com.mlreef.rest.api.DataProcessorApiTest.Can retrieve all DataProcessors filtered(DataProcessorApiTest.kt:110)
	at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
	at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
	at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
	at java.base/java.lang.reflect.Method.invoke(Method.java:566)
	at org.junit.platform.commons.util.ReflectionUtils.invokeMethod(ReflectionUtils.java:532)
	at org.junit.jupiter.engine.execution.ExecutableInvoker.invoke(ExecutableInvoker.java:115)
	at org.junit.jupiter.engine.descriptor.TestMethodTestDescriptor.lambda$invokeTestMethod$6(TestMethodTestDescriptor.java:171)
	at org.junit.platform.engine.support.hierarchical.ThrowableCollector.execute(ThrowableCollector.java:72)
	at org.junit.jupiter.engine.descriptor.TestMethodTestDescriptor.invokeTestMethod(TestMethodTestDescriptor.java:167)
	at org.junit.jupiter.engine.descriptor.TestMethodTestDescriptor.execute(TestMethodTestDescriptor.java:114)
	at org.junit.jupiter.engine.descriptor.TestMethodTestDescriptor.execute(TestMethodTestDescriptor.java:59)
	at org.junit.platform.engine.support.hierarchical.NodeTestTask.lambda$executeRecursively$4(NodeTestTask.java:108)
	at org.junit.platform.engine.support.hierarchical.ThrowableCollector.execute(ThrowableCollector.java:72)
	at org.junit.platform.engine.support.hierarchical.NodeTestTask.executeRecursively(NodeTestTask.java:98)
	at org.junit.platform.engine.support.hierarchical.NodeTestTask.execute(NodeTestTask.java:74)
	at java.base/java.util.ArrayList.forEach(ArrayList.java:1540)
	at org.junit.platform.engine.support.hierarchical.SameThreadHierarchicalTestExecutorService.invokeAll(SameThreadHierarchicalTestExecutorService.java:38)
	at org.junit.platform.engine.support.hierarchical.NodeTestTask.lambda$executeRecursively$4(NodeTestTask.java:112)
	at org.junit.platform.engine.support.hierarchical.ThrowableCollector.execute(ThrowableCollector.java:72)
	at org.junit.platform.engine.support.hierarchical.NodeTestTask.executeRecursively(NodeTestTask.java:98)
	at org.junit.platform.engine.support.hierarchical.NodeTestTask.execute(NodeTestTask.java:74)

[FloHin]

If maintainers think this is a good idea, I would fork and work on that, happy to contribute.

[wilkinsona]

Thanks for reporting this, @FloHin. There's definitely room for improvement here. Thanks to the flexibility of the template-based approach, I'm not sure how precisely the problem can be described. However, I'm pretty sure that it could be better than it currently is. If you have some time to work on some improvements, a pull request would be great. Thanks!

[wilkinsona]

Unfortunately, when a failure like this occurs, JMustache does not provide enough information to identify exactly which field did not have a description. The best that can be done is to provide a little bit more context, including the template that was being rendered, when the failure occurred. Something like this:

org.springframework.restdocs.templates.TemplateRenderingException: Failed to render 'request-fields'. No value for 'description' on line 7:

  1. |===
  2. |Path|Type|Description
  3. 
  4. {{#fields}}
  5. |{{#tableCellContent}}`+{{path}}+`{{/tableCellContent}}
  6. |{{#tableCellContent}}`+{{type}}+`{{/tableCellContent}}
  7. |{{#tableCellContent}}{{description}}{{/tableCellContent}}
  8. 
  9. {{/fields}}
 10. |===

	at org.springframework.restdocs.templates.mustache.MustacheTemplate.render(MustacheTemplate.java:95)
	at org.springframework.restdocs.snippet.TemplatedSnippet.document(TemplatedSnippet.java:82)
	at org.springframework.restdocs.payload.RequestFieldsSnippetTests.missingDescription(RequestFieldsSnippetTests.java:58)
	at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
	at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
	at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
	at java.lang.reflect.Method.invoke(Method.java:498)
	at org.junit.runners.model.FrameworkMethod$1.runReflectiveCall(FrameworkMethod.java:50)
	at org.junit.internal.runners.model.ReflectiveCallable.run(ReflectiveCallable.java:12)
	at org.junit.runners.model.FrameworkMethod.invokeExplosively(FrameworkMethod.java:47)
	at org.junit.internal.runners.statements.InvokeMethod.evaluate(InvokeMethod.java:17)
	at org.junit.rules.RunRules.evaluate(RunRules.java:20)
	at org.junit.runners.ParentRunner.runLeaf(ParentRunner.java:325)
	at org.junit.runners.BlockJUnit4ClassRunner.runChild(BlockJUnit4ClassRunner.java:78)
	at org.junit.runners.BlockJUnit4ClassRunner.runChild(BlockJUnit4ClassRunner.java:57)
	at org.junit.runners.ParentRunner$3.run(ParentRunner.java:290)
	at org.junit.runners.ParentRunner$1.schedule(ParentRunner.java:71)
	at org.junit.runners.ParentRunner.runChildren(ParentRunner.java:288)
	at org.junit.runners.ParentRunner.access$000(ParentRunner.java:58)
	at org.junit.runners.ParentRunner$2.evaluate(ParentRunner.java:268)
	at org.junit.runners.ParentRunner.run(ParentRunner.java:363)
	at org.junit.runners.Suite.runChild(Suite.java:128)
	at org.junit.runners.Suite.runChild(Suite.java:27)
	at org.junit.runners.ParentRunner$3.run(ParentRunner.java:290)
	at org.junit.runners.ParentRunner$1.schedule(ParentRunner.java:71)
	at org.junit.runners.ParentRunner.runChildren(ParentRunner.java:288)
	at org.junit.runners.ParentRunner.access$000(ParentRunner.java:58)
	at org.junit.runners.ParentRunner$2.evaluate(ParentRunner.java:268)
	at org.junit.runners.ParentRunner.run(ParentRunner.java:363)
	at org.eclipse.jdt.internal.junit4.runner.JUnit4TestReference.run(JUnit4TestReference.java:89)
	at org.eclipse.jdt.internal.junit.runner.TestExecution.run(TestExecution.java:41)
	at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.runTests(RemoteTestRunner.java:542)
	at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.runTests(RemoteTestRunner.java:770)
	at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.run(RemoteTestRunner.java:464)
	at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.main(RemoteTestRunner.java:210)
Caused by: org.springframework.restdocs.mustache.MustacheException$Context: No key, method or field with name 'description' on line 7
	at org.springframework.restdocs.mustache.Mustache$VariableSegment.execute(Mustache.java:789)
	at org.springframework.restdocs.mustache.Template$1.execute(Template.java:131)
	at org.springframework.restdocs.mustache.Template$1.execute(Template.java:124)
	at org.springframework.restdocs.mustache.Template$Fragment.execute(Template.java:59)
	at org.springframework.restdocs.templates.mustache.AsciidoctorTableCellContentLambda.execute(AsciidoctorTableCellContentLambda.java:36)
	at org.springframework.restdocs.mustache.Mustache$SectionSegment.execute(Mustache.java:856)
	at org.springframework.restdocs.mustache.Mustache$BlockSegment.executeSegs(Mustache.java:827)
	at org.springframework.restdocs.mustache.Mustache$SectionSegment.execute(Mustache.java:848)
	at org.springframework.restdocs.mustache.Template.executeSegs(Template.java:114)
	at org.springframework.restdocs.mustache.Template.execute(Template.java:91)
	at org.springframework.restdocs.mustache.Template.execute(Template.java:82)
	at org.springframework.restdocs.templates.mustache.MustacheTemplate.render(MustacheTemplate.java:84)
	... 34 more

[wilkinsona]

It may be possible to improve on the above using a Lambda or by implementing CustomContext. Both will require changes that are too broad for a 2.0.x release.

[DavJaveiro]

Hi, I’m interested in investigating this issue.

I noticed that it has been open for some time and that there was a previous attempt to work on it, so I’d like to confirm whether the issue is still relevant and whether a contribution would still be welcome.

If so, my plan would be to first reproduce the behavior on the current main branch with a focused regression test, and then propose a small improvement to the diagnostic message so that it identifies both the missing template property and the affected descriptor path.

Would this issue still be available for contribution, and would this approach be appropriate?

[wilkinsona]

@DavJaveiro if you have the time, an investigation into how this could be improved would be much appreciated. Assuming that #678 (comment) is still applicable, figuring out how to improve things without being too disruptive is likely to be the hardest part.

[DavJaveiro]

Thanks, @wilkinsona . I’d be happy to work on this.

I’ll investigate the existing validation, add regression test coverage, and prepare a focused pull request.
I’ll post an update here if I run into any questions while working on it.

[wilkinsona]

Excellent, thanks. I've assigned the issue to you.