001/*
002 * Copyright 2002-2018 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.test.web.servlet.setup;
018
019import javax.servlet.Filter;
020
021import org.springframework.test.web.servlet.MockMvcBuilder;
022import org.springframework.test.web.servlet.RequestBuilder;
023import org.springframework.test.web.servlet.ResultHandler;
024import org.springframework.test.web.servlet.ResultMatcher;
025
026/**
027 * Defines common methods for building a {@code MockMvc}.
028 *
029 * @author Rossen Stoyanchev
030 * @since 4.1
031 * @param <B> a self reference to the builder type
032 */
033public interface ConfigurableMockMvcBuilder<B extends ConfigurableMockMvcBuilder<B>> extends MockMvcBuilder {
034
035        /**
036         * Add filters mapped to any request (i.e. "/*"). For example:
037         * <pre class="code">
038         * mockMvcBuilder.addFilters(springSecurityFilterChain);
039         * </pre>
040         * <p>is the equivalent of the following web.xml configuration:
041         * <pre class="code">
042         * &lt;filter-mapping&gt;
043         *     &lt;filter-name&gt;springSecurityFilterChain&lt;/filter-name&gt;
044         *     &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
045         * &lt;/filter-mapping&gt;
046         * </pre>
047         * <p>Filters will be invoked in the order in which they are provided.
048         * @param filters the filters to add
049         */
050        <T extends B> T addFilters(Filter... filters);
051
052        /**
053         * Add a filter mapped to a specific set of patterns. For example:
054         * <pre class="code">
055         * mockMvcBuilder.addFilters(myResourceFilter, "/resources/*");
056         * </pre>
057         * <p>is the equivalent of:
058         * <pre class="code">
059         * &lt;filter-mapping&gt;
060         *     &lt;filter-name&gt;myResourceFilter&lt;/filter-name&gt;
061         *     &lt;url-pattern&gt;/resources/*&lt;/url-pattern&gt;
062         * &lt;/filter-mapping&gt;
063         * </pre>
064         * <p>Filters will be invoked in the order in which they are provided.
065         * @param filter the filter to add
066         * @param urlPatterns the URL patterns to map to; if empty, "/*" is used by default
067         */
068        <T extends B> T addFilter(Filter filter, String... urlPatterns);
069
070        /**
071         * Define default request properties that should be merged into all
072         * performed requests. In effect this provides a mechanism for defining
073         * common initialization for all requests such as the content type, request
074         * parameters, session attributes, and any other request property.
075         *
076         * <p>Properties specified at the time of performing a request override the
077         * default properties defined here.
078         * @param requestBuilder a RequestBuilder; see static factory methods in
079         * {@link org.springframework.test.web.servlet.request.MockMvcRequestBuilders}
080         */
081        <T extends B> T defaultRequest(RequestBuilder requestBuilder);
082
083        /**
084         * Define a global expectation that should <em>always</em> be applied to
085         * every response. For example, status code 200 (OK), content type
086         * {@code "application/json"}, etc.
087         * @param resultMatcher a ResultMatcher; see static factory methods in
088         * {@link org.springframework.test.web.servlet.result.MockMvcResultMatchers}
089         */
090        <T extends B> T alwaysExpect(ResultMatcher resultMatcher);
091
092        /**
093         * Define a global action that should <em>always</em> be applied to every
094         * response. For example, writing detailed information about the performed
095         * request and resulting response to {@code System.out}.
096         * @param resultHandler a ResultHandler; see static factory methods in
097         * {@link org.springframework.test.web.servlet.result.MockMvcResultHandlers}
098         */
099        <T extends B> T alwaysDo(ResultHandler resultHandler);
100
101        /**
102         * Whether to enable the DispatcherServlet property
103         * {@link org.springframework.web.servlet.DispatcherServlet#setDispatchOptionsRequest
104         * dispatchOptionsRequest} which allows processing of HTTP OPTIONS requests.
105         */
106        <T extends B> T dispatchOptions(boolean dispatchOptions);
107
108        /**
109         * Add a {@code MockMvcConfigurer} that automates MockMvc setup and
110         * configures it for some specific purpose (e.g. security).
111         * <p>There is a built-in {@link SharedHttpSessionConfigurer} that can be
112         * used to re-use the HTTP session across requests. 3rd party frameworks
113         * like Spring Security also use this mechanism to provide configuration
114         * shortcuts.
115         * @see SharedHttpSessionConfigurer
116         */
117        <T extends B> T apply(MockMvcConfigurer configurer);
118
119}