1 # Example Pact + Siren project
2 Example project using [Siren](https://github.com/kevinswiber/siren) for hypermedia entities and testing with Pact.
4 This project has two sub-projects, a provider springboot project which is using `spring-hateoas-siren` to provide Siren
5 responses and a Javascript consumer project using `ketting` to parse and navigate the Siren responses.
9 The provider project is a springboot application with Siren support provided by `spring-hateoas-siren`. It has two
10 resources, a root resource which provides links to the other resources and an order resource for dealing with orders
15 This just provides the links to the other resources.
29 "href": "http://localhost:8080/orders"
37 This provides all the CRUD operations on Orders: fetch all orders, fetch an order by ID, update a resource or delete one.
62 "href": "http://localhost:8080/orders/1234"
69 "href": "http://localhost:8080/orders/1234"
74 "href": "http://localhost:8080/orders/1234"
84 "href": "http://localhost:8080/orders"
92 This is a simple Javascript application that uses [Ketting](https://github.com/badgateway/ketting) which is a
93 hypermedia client for javascript. It has a single function in `consumer/src/consumer.js` that navigates the links from the provider to find the
94 orders resource, get all the orders, find the first one and execute the delete action.
96 The consumer does the following:
98 1. Get the root resource
99 2. Find the orders relation
100 3. Execute a GET to the URL of the orders relation
101 4. Extract the first order entity from the embedded entities
102 5. Find the delete action for that order
103 6. Execute the action (which executes a DELETE to the URL of the action)
107 The problem with using normal Pact tests to test this scenario is that Siren responses contain URLs to the resources and
108 actions. The URLs when running the consumer test will be different than those when verifying the provider. This will
109 result in a verification failure.
111 To get round this problem, we use the `url` matcher function from the consumer Pact DSL. This function takes a list of
112 path fragments. The path fragments can be either plain strings or regular expressions. It then constructs
113 the actual URL to use in the consumer test using the mock servers base URL, and a regular expression matcher that can
114 match the URLs in the provider verification test.
116 ### Dealing with hypermedia formats like Siren actions
118 Siren takes hypermedia links one step further by introducing resource actions. These encode the URL, HTTP method and
119 optionally any required parameters needed to make the requests for the actions supported by the resource.
121 The problem could then arise that the consumer make only use a few actions provided by the provider. We would want to
122 ensure that these actions are present in the list for the resource, and ignore the ones we are not using. The other issue
123 is that our tests should not be dependent on the order of the actions.
125 This is where the "array contains" matcher can help. It will allow us to match the resource actions for the ones we are
126 using, and ignore the others. It will also not depend on the order the actions are returned.
128 This is the actions for the order resource in the provider:
136 "href": "http://localhost:8080/orders/6774860028109588394"
141 "href": "http://localhost:8080/orders/6774860028109588394"
144 "name": "changeStatus",
146 "href": "http://localhost:8080/orders/6774860028109588394/status"
152 For example, in the consumer test we can specify:
155 "actions": arrayContaining(
159 "href": url(["orders", regex("\\d+", "1234")])
164 "href": url(["orders", regex("\\d+", "1234")])
169 This will match the actions if they contain the update and delete actions. it will ignore the other actions.
171 You can see this in work if you remove one of the controller methods in the provider. For instance, if we commented out
172 the delete endpoint, and then run the pact verification in the provider, we get this error:
175 $ ./gradlew pactverify
180 /\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
181 ( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
182 \\/ ___)| |_)| | | | | || (_| | ) ) ) )
183 ' |____| .__|_| |_|_| |_\__, | / / / /
184 =========|_|==============|___/=/_/_/_/
185 :: Spring Boot :: (v2.3.4.RELEASE)
187 2020-11-09 14:53:32.046 INFO 39485 --- [ main] i.p.e.s.SirenProviderApplication : Starting SirenProviderApplication on ronald-P95xER with PID 39485 (/home/ronald/Development/Projects/Pact/example-siren/provider/build/libs/siren-provider-0.0.1.jar started by ronald in /home/ronald/Development/Projects/Pact/example-siren/provider)
188 2020-11-09 14:53:32.048 INFO 39485 --- [ main] i.p.e.s.SirenProviderApplication : No active profile set, falling back to default profiles: default
189 2020-11-09 14:53:32.797 INFO 39485 --- [ main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat initialized with port(s): 8080 (http)
190 2020-11-09 14:53:32.808 INFO 39485 --- [ main] o.apache.catalina.core.StandardService : Starting service [Tomcat]
191 2020-11-09 14:53:32.808 INFO 39485 --- [ main] org.apache.catalina.core.StandardEngine : Starting Servlet engine: [Apache Tomcat/9.0.38]
192 2020-11-09 14:53:32.870 INFO 39485 --- [ main] o.a.c.c.C.[Tomcat].[localhost].[/] : Initializing Spring embedded WebApplicationContext
193 2020-11-09 14:53:32.870 INFO 39485 --- [ main] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 759 ms
194 2020-11-09 14:53:33.071 INFO 39485 --- [ main] o.s.s.concurrent.ThreadPoolTaskExecutor : Initializing ExecutorService 'applicationTaskExecutor'
195 2020-11-09 14:53:33.221 INFO 39485 --- [ main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat started on port(s): 8080 (http) with context path ''
196 2020-11-09 14:53:33.229 INFO 39485 --- [ main] i.p.e.s.SirenProviderApplication : Started SirenProviderApplication in 1.53 seconds (JVM running for 1.903)
197 java -jar /home/ronald/Development/Projects/Pact/example-siren/provider/build/libs/siren-provider-0.0.1.jar is ready.
199 > Task :pactVerify_Siren_Order_Provider FAILED
201 Verifying a pact between Siren Consumer and Siren Order Provider
202 [Using File /home/ronald/Development/Projects/Pact/example-siren/consumer/pacts/Siren Order Provider-Siren Order Service.json]
204 returns a response which
205 has status code 200 (OK)
206 has a matching body (OK)
208 returns a response which
209 has status code 200 (OK)
210 has a matching body (FAILED)
212 returns a response which
213 has status code 200 (FAILED)
214 has a matching body (OK)
216 NOTE: Skipping publishing of verification results as it has been disabled (pact.verifier.publishResults is not 'true')
221 1) Verifying a pact between Siren Consumer and Siren Order Provider - get all orders
223 1.1) body: $.entities.0.actions Variant at index 1 ({"href":http://localhost:9000/orders/1234,"method":DELETE,"name":delete}) was not found in the actual list
227 - "href": "http://localhost:9000/orders/1234",
228 + "href": "http://localhost:8080/orders/7779028774458252624",
233 - "href": "http://localhost:9000/orders/1234",
234 - "method": "DELETE",
236 + "href": "http://localhost:8080/orders/7779028774458252624/status",
238 + "name": "changeStatus"
243 1.2) status: expected status of 200 but was 405
247 FAILURE: Build failed with an exception.
250 There were 2 non-pending pact failures for provider Siren Order Provider
253 Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output. Run with --scan to get full insights.
255 * Get more help at https://help.gradle.org
257 Deprecated Gradle features were used in this build, making it incompatible with Gradle 7.0.
258 Use '--warning-mode all' to show the individual deprecation warnings.
259 See https://docs.gradle.org/6.6.1/userguide/command_line_interface.html#sec:command_line_warnings
262 8 actionable tasks: 6 executed, 2 up-to-date