Spring MVC Test utils

Test library aimed to ease Spring MVC form validation tests. Easily post an entire form to a given url.

See MockMvcRequestBuilderUtils

More details here: blog.florianlopes.io

How to use?

Add this dependency to your pom.xml file:

<dependency>
    <groupId>io.florianlopes</groupId>
    <artifactId>spring-mvc-test-utils</artifactId>
    <version>3.2.0</version>
    <scope>test</scope>
</dependency>

Note: since version 4.0.0, Java 11 is no longer supported, Java 17 is the minimum supported version.

This library is tested with Spring Framework 6.1.12 along with Java 17 and 21 ( see smoke-tests and build.yml workflow)

MockMvcRequestBuilderUtils.postForm("/url", formObject);

Example:

@Test
public void testSimpleFields() throws Exception {
    final MockHttpServletRequestBuilder mockHttpServletRequestBuilder = MockMvcRequestBuilderUtils.postForm("/test",
            new AddUserForm("John", "Doe", null, new Address(1, "Street", 5222, "New York")));
    final MockHttpServletRequest request = mockHttpServletRequestBuilder.buildRequest(this.servletContext);

    assertEquals("John", request.getParameter("firstName"));
    assertEquals("New York", request.getParameter("address.city"));
}

Usage with MockMvc:

final AddUserForm addUserForm = new AddUserForm("John", "Doe", null, new Address(1, "Street", 5222, "New York")));

mockMvc.perform(MockMvcRequestBuilderUtils.postForm("/users", addUserForm))
        .andExpect(MockMvcResultMatchers.model().hasNoErrors());

Using with() syntax (FormRequestPostProcessor):

final AddUserForm addUserForm = new AddUserForm("John", "Doe", null, new Address(1, "Street", 5222, "New York")));

// POST
mockMvc.perform(post("/users").with(MockMvcRequestBuilderUtils.form(addUserForm)))
        .andExpect(MockMvcResultMatchers.model().hasNoErrors());

// GET
mockMvc.perform(get("/users").with(MockMvcRequestBuilderUtils.form(addUserForm)))
        .andExpect(MockMvcResultMatchers.model().hasNoErrors());

// PUT
mockMvc.perform(put("/users").with(MockMvcRequestBuilderUtils.form(addUserForm)))
        .andExpect(MockMvcResultMatchers.model().hasNoErrors());

Register property editor(s)

This tool relies on default Spring's property editors ( see https://github.com/spring-projects/spring-framework/blob/main/spring-beans/src/main/java/org/springframework/beans/PropertyEditorRegistrySupport.java#L200).

If you want to override one of those registered by default, simple use the MockMvcRequestBuilderUtils.registerPropertyEditor(...) method:

MockMvcRequestBuilderUtils.registerPropertyEditor(LocalDate.class, new CustomLocalDatePropertyEditor("dd/MM/yyyy"));

final AddUserForm addUserForm = new AddUserForm("John", "Doe", LocalDate.now(), null);
final MockHttpServletRequestBuilder mockHttpServletRequestBuilder = MockMvcRequestBuilderUtils.postForm(POST_FORM_URL, addUserForm);

MockHttpServletRequest request = mockHttpServletRequestBuilder.buildRequest(this.servletContext);
assertEquals(LocalDate.now().format(DateTimeFormatter.ofPattern("dd/MM/yyyy")), request.getParameter("birthDate"));

Limitations and restrictions

This helper utility handles your form objects using the Java Reflection API. This implies some restrictions in the usage within your test cases:

• As long as you use simple, common Java types like String, etc, the mocked HTTPServletRequest should not fail to be processed by data binding.

• You can always provide a custom property editor (see above).

• Converting data using classes from the Java Collection API is supported since version 1.0.0. The parameters will follow the convention name[index] = value.

  • Currently, no multidimensional collections (like array of arrays) are supported.

• Converting data using classes from the Java Map API is supported in a simple manner since version 1.1.0. The parameters will follow the convention name[key] = value.

  • Currently, no map of maps is supported, only simple datatypes with key and value easily transformable to a String.

• As a last resort, your properties will be converted using the toString() method of the member object under the name of the object.

Contributing

Feel free to contribute using this guide:

1. Fork this project
2. Clone your forked repository git clone git@github.com:{your-username}/spring-mvc-test-utils.git
3. Add a new remote pointing to the original repository git remote add upstream git@github.com:flopes/spring-mvc-test-utils.git
4. Create a new branch for your feature git branch -b my-feature
5. Commit your changes (and squash them if necessary using git rebase -i or git add -p)
6. Pull the latest changes from the original repository git checkout main && git pull --rebase upstream main
7. Rebase main branch with your feature git checkout my-feature && git rebase main Solve any existing conflicts
8. Push your changes and create a PR on GitHub git push -u origin my-feature Go to the original repository and create a new PR with comments.