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 base URL,
112 and a list of 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, and a regular expression matcher that can match the URLs in the provider
116 To show this working, the consumer Pact test has the mock server running on port 9000, while the provider will be running on port 8080.
118 ### Dealing with hypermedia formats like Siren actions
120 Siren takes hypermedia links one step further by introducing resource actions. These encode the URL, HTTP method and
121 optionally any required parameters needed to make the requests for the actions supported by the resource.
123 The problem could then arise that the consumer make only use a few actions provided by the provider. We would want to
124 ensure that these actions are present in the list for the resource, and ignore the ones we are not using. The other issue
125 is that our tests should not be dependent on the order of the actions.
127 This is where the "array contains" matcher can help. It will allow us to match the resource actions for the ones we are
128 using, and ignore the others. It will also not depend on the order the actions are returned.
130 This is the actions for the order resource in the provider:
138 "href": "http://localhost:8080/orders/6774860028109588394"
143 "href": "http://localhost:8080/orders/6774860028109588394"
146 "name": "changeStatus",
148 "href": "http://localhost:8080/orders/6774860028109588394/status"
154 For example, in the consumer test we can specify:
157 "actions": arrayContaining(
161 "href": url("http://localhost:9000", ["orders", regex("\\d+", "1234")])
166 "href": url("http://localhost:9000", ["orders", regex("\\d+", "1234")])
171 This will match the actions if they contain the update and delete actions. it will ignore the other actions.
173 You can see this in work if you remove one of the controller methods in the provider. For instance, if we commented out
174 the delete endpoint, and then run the pact verification in the provider, we get this error:
177 $ ./gradlew pactverify
182 /\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
183 ( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
184 \\/ ___)| |_)| | | | | || (_| | ) ) ) )
185 ' |____| .__|_| |_|_| |_\__, | / / / /
186 =========|_|==============|___/=/_/_/_/
187 :: Spring Boot :: (v2.3.4.RELEASE)
189 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)
190 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
191 2020-11-09 14:53:32.797 INFO 39485 --- [ main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat initialized with port(s): 8080 (http)
192 2020-11-09 14:53:32.808 INFO 39485 --- [ main] o.apache.catalina.core.StandardService : Starting service [Tomcat]
193 2020-11-09 14:53:32.808 INFO 39485 --- [ main] org.apache.catalina.core.StandardEngine : Starting Servlet engine: [Apache Tomcat/9.0.38]
194 2020-11-09 14:53:32.870 INFO 39485 --- [ main] o.a.c.c.C.[Tomcat].[localhost].[/] : Initializing Spring embedded WebApplicationContext
195 2020-11-09 14:53:32.870 INFO 39485 --- [ main] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 759 ms
196 2020-11-09 14:53:33.071 INFO 39485 --- [ main] o.s.s.concurrent.ThreadPoolTaskExecutor : Initializing ExecutorService 'applicationTaskExecutor'
197 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 ''
198 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)
199 java -jar /home/ronald/Development/Projects/Pact/example-siren/provider/build/libs/siren-provider-0.0.1.jar is ready.
201 > Task :pactVerify_Siren_Order_Provider FAILED
203 Verifying a pact between Siren Consumer and Siren Order Provider
204 [Using File /home/ronald/Development/Projects/Pact/example-siren/consumer/pacts/Siren Order Provider-Siren Order Service.json]
206 returns a response which
207 has status code 200 (OK)
208 has a matching body (OK)
210 returns a response which
211 has status code 200 (OK)
212 has a matching body (FAILED)
214 returns a response which
215 has status code 200 (FAILED)
216 has a matching body (OK)
218 NOTE: Skipping publishing of verification results as it has been disabled (pact.verifier.publishResults is not 'true')
223 1) Verifying a pact between Siren Consumer and Siren Order Provider - get all orders
225 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
229 - "href": "http://localhost:9000/orders/1234",
230 + "href": "http://localhost:8080/orders/7779028774458252624",
235 - "href": "http://localhost:9000/orders/1234",
236 - "method": "DELETE",
238 + "href": "http://localhost:8080/orders/7779028774458252624/status",
240 + "name": "changeStatus"
245 1.2) status: expected status of 200 but was 405
249 FAILURE: Build failed with an exception.
252 There were 2 non-pending pact failures for provider Siren Order Provider
255 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.
257 * Get more help at https://help.gradle.org
259 Deprecated Gradle features were used in this build, making it incompatible with Gradle 7.0.
260 Use '--warning-mode all' to show the individual deprecation warnings.
261 See https://docs.gradle.org/6.6.1/userguide/command_line_interface.html#sec:command_line_warnings
264 8 actionable tasks: 6 executed, 2 up-to-date