<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Tom Muc on Medium]]></title>
        <description><![CDATA[Stories by Tom Muc on Medium]]></description>
        <link>https://medium.com/@tommuc?source=rss-e63e806fd875------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*IbUPZLm0a8n3iOxPTp7Snw.jpeg</url>
            <title>Stories by Tom Muc on Medium</title>
            <link>https://medium.com/@tommuc?source=rss-e63e806fd875------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sun, 22 Nov 2026 13:59:34 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@tommuc/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[DynamoDB mistakes we made (so you don’t have to)]]></title>
            <link>https://codeburst.io/dynamodb-mistakes-we-made-so-you-dont-have-to-cc7687d4b3bf?source=rss-e63e806fd875------2</link>
            <guid isPermaLink="false">https://medium.com/p/cc7687d4b3bf</guid>
            <category><![CDATA[aws]]></category>
            <category><![CDATA[dynamodb]]></category>
            <category><![CDATA[database]]></category>
            <category><![CDATA[nosql]]></category>
            <category><![CDATA[microservices]]></category>
            <dc:creator><![CDATA[Tom Muc]]></dc:creator>
            <pubDate>Mon, 11 Mar 2024 15:46:52 GMT</pubDate>
            <atom:updated>2024-03-11T15:46:52.270Z</atom:updated>
            <content:encoded><![CDATA[<p>The NoSQL approach has some learning curve to it and there are many things to remember to <em>get it right. </em>Here’s a list of mistakes and problems we faced when introducing the single-table DynamoDB approach to our microservices.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*nmT9ut2BpBYt3uKV2w98fQ.jpeg" /></figure><h3>Deletion <em>is</em> an access pattern</h3><p>We‘ve been very thorough while working on a DynamoDB data model design. We got the read and write access patterns noted down as suggested. We verified how to achieve them with the proposed model. Whenever we caught any limitation or problem we revised the model and started again. In the end, we decided to put the 7th version live.</p><p>After a while, we looked at the AWS billing only to realise we hadn’t paid enough attention to our data storage costs — they were growing way faster than the usage of our application.</p><p>What went wrong? Our application did not expose to its clients any way to delete entities, so we skipped it during our access pattern discussions. But it doesn’t mean we needed to keep all the data forever! For instance, we introduced a <a href="https://microservices.io/patterns/data/transactional-outbox.html">transactional-outbox</a>-like pattern, saving an event payload together with an entity within a single DynamoDB transaction. Once the event was published or expired we didn’t need it anymore — the access pattern we totally missed.</p><p>What did we do about it? We revised the data we stored in the DynamoDB table from the perspective of:</p><ul><li><em>an expiration date</em>— is this still useful or needed after a week? A month? A year?</li><li><em>an environment — </em>do we need to keep the data in development or test environments for the same amount of time as in production?</li><li><em>expiration triggers — </em>is there any business process that would notify us the retention period for our data is over? Think of removing the detailed order data after the order was successfully delivered, or a history of product price changes once the product is no longer offered to the customers.</li></ul><h4>Lessons learned</h4><ul><li>Define <a href="https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/time-to-live-ttl-how-to.html"><em>time-to-live </em>(TTL)</a> whenever you know it upfront to limit the amount of unused data stored in your table.</li><li>If your domain allows it, prefer using TTL over externally-triggered removal processes. You have to pay for theDeleteItem , which is a write action, whereas <a href="https://stackoverflow.com/questions/63346408/can-the-ttl-feature-on-dynamodb-be-used-as-a-free-alternative-to-actually-deleti">TTL-based removal comes for free</a>!</li><li>If some of your data has to be kept for a long time, but it’d be accessed rather sporadically (i.e. auditing details) consider moving them to the dedicated <a href="https://aws.amazon.com/dynamodb/standard-ia/">Standard Infrequently Accessed table (Standard-IA)</a>.</li></ul><h3>Keep GSI names generic</h3><p>DynamoDB comes with a hard limit of 20 Global Secondary Indexes (GSI) per table. It seems quite limiting at first, but knowing the <a href="https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-gsi-overloading.html">GSI overloading</a> technique, you can fit plenty of access patterns into a single table.</p><p>We didn’t quite get that while working on our first microservice backed by a single-table DynamoDB model. We defined our first GSI — orderContext— with a hash key named orderContext and a range key named contextTimestamp.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*BT6vvxvCRcwyOYOWDTeMyw.png" /><figcaption>Single table holding order prices (ids simplified for readability)</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*yrh68a9IrHQxCobnStpjXA.png" /><figcaption>Order-context GSI representing an order-to-prices view</figcaption></figure><p>Of course, the order-context GSI’s structure is readable and self-explanatory to developers, but it does not make sense if you want to reuse it (overload it) with a different data set, and we’ve quickly realised that we need to add order item prices to the same table.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*w_QtaM-oGrPC3N0lDoqeHg.png" /><figcaption>Single table holding order and item prices</figcaption></figure><p>If we were to introduce a reverse mapping <em>order-to-item</em>, the existing order-context GSI would not make sense — see the orderContextTimestamp column containing an item id?</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*uWTBLFNNAUd02AA6A0lFPw.png" /><figcaption>Order-context GSI with order and item prices</figcaption></figure><p>It may look like a minor problem, but we’ve effectively wasted one of the 20 available GSIs. Having it named in a more generic way does not suggest any characteristics of the data collection underneath. It allows future additions and leaves the complexity on the application side.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-Cc4NfHJWznkeMfiGdxGYw.png" /></figure><h4>Lessons learned</h4><ul><li>use generic GSI hash key and range key names, i.e. GSI_1_PK and GSI_1_SK to make them reusable (overridable) in the future.</li></ul><h3>GSI updates in baby steps</h3><p>We use <a href="https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-dynamodb-table.html">CloudFormation</a> to define the structure of our DynamoDB tables. It’s just convenient to keep the “schema” details, or — I should say — the infrastructure defined as code (IaC).</p><p>At times where we had to update the GSI structure by, for example, introducing more projected attributes to it or adding a range key. Unfortunately, in DynamoDB terms, it means dropping the existing GSI, recreating it <em>from scratch</em>, waiting for the data to be backfilled, and <em>voilà</em>, you’re done.</p><p>Remember that you can only create or delete one GSI at a time — a thing we forgot about multiple times… Otherwise, you’ll see the following error during the CloudFormation stack update:</p><pre>UPDATE_FAILED - AWS::DynamoDB::Table - someTable - Cannot perform more than one GSI creation or deletion in a single update</pre><h4>Lessons learned</h4><ul><li>Always think through the structure of your GSIs, including the projected attributes. In case you missed anything, remember to change only one GSI at a time.</li><li>When using CloudFormation it’s important to define only the attributes that are used in a table or GSI key schema (either as PK or SK) in the AttributeDefinition section. Any extra attribute may cause an exception.</li><li>To avoid any “downtime” issues because of a missing GSI, you try creating a new one with a different name and desired structure first, deploy code changes to use it in your application, and finally trigger the removal of the old one.</li></ul><h3>GSI storage amplification</h3><p>DynamoDB comes with <a href="https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html#GSI.Projections">3 types of attribute projection</a> in Global Secondary Indexes: ALL, INCLUDE, and KEYS_ONLY. Whenever you define a new GSI think carefully about what data it <em>needs</em> to store. The thing to remember is that data for <em>each projected field</em> in<em> each GSI</em> you define will be <em>copied</em>, which effectively multiplies the cost of its storage.</p><p>Imagine a table of orders, including an order id, customer id, some timestamp, and a heavy JSON payload describing all the details of products, prices, and promotions:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ZEB3u6sR3Zyqm6VzWDjaNQ.png" /><figcaption>Orders main table (ids simplified for readability)</figcaption></figure><p>If we define a GSI to get orders from a given customer with the projection type set to ALL, we will have a table like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*hy7yfUdI6DxaZGVgflhQcA.png" /><figcaption>Customer orders GSI with ALL attributes projected to it</figcaption></figure><p>Notice that it contains the payload attribute, which means you’ll pay for the heavy payload storage twice — once to store it in the main table, and another one to keep it in the GSI.</p><p>If we used the projection type set to KEYS_ONLY, it’d look as follows:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*f6ZonX7LM4eJXEVoNymBTA.png" /><figcaption>Customer orders GSI with KEYS_ONLY projected to it</figcaption></figure><p>The GSI is still quite useful, but the heavy JSON payload is stored only once, limiting the storage costs.</p><h4>Lessons learned</h4><ul><li>Do your math (i.e. using <a href="https://calculator.aws/">AWS Pricing Calculator</a>) and verify if it’s worth storing the same data multiple times, or rather it’s better to use 2 separate reads — one to get the main entity’s key from the GSI, and another to get the full payload.</li><li>Refrain from using ALL attributes projection, or including data-heavy attributes in INCLUDE projection to <a href="https://aws.amazon.com/blogs/database/single-table-vs-multi-table-design-in-amazon-dynamodb/#:~:text=Use%20single%2Dtable%20design%20to%20reduce%20costs%20across%20large%20items">cut down storage costs</a>.</li><li>The smaller the set of attributes in a GSI, the faster it is to populate and provides lower latencies.</li><li>The smaller the index, the lower the costs of <em>storage</em> and <em>writes.</em></li></ul><h3>GSIs have their limits too</h3><p>The AWS docs recommend using <a href="https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-partition-key-uniform-load.html">uniformly distributed keys</a> in your DynamoDB tables for optimal performance — think of UUIDs rather than a limited set of order statuses.</p><p>If you don’t spread your workload evenly you may run into the “hot” partitions problem, where certain data is read/written so frequently the requests exceed the <a href="https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-partition-key-design.html">throughput limits of 3000 RCU/s or 1000 WCU/s</a> and get throttled.</p><p>We knew it when we built a write-heavy application in my team. We decided to use a compound key consisting of a few UUIDs — product id and tenant id —as the PK of our main table to spread data evenly.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*GToxjdSVs3o3aks_ML3gQQ.png" /><figcaption>Product table (ids simplified for readability)</figcaption></figure><p>What we overlooked though is that GSIs have their throughput limits too! And we did not distribute the partitions as well as in the main table:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*IdExKyfPT-vTmKTnJuf0IA.png" /><figcaption>Tenant’s products GSI</figcaption></figure><p>Whenever a single tenant started to define a lot of product prices at the same time, the main table worked well, but we faced write request throttling for GSI.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*r6g4c2XQb00Ol3cNdySPgA.png" /><figcaption>The main table without write throttled requests</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*DWVh_TFxZHxH_cPYr8FHKw.png" /><figcaption>The GSI with write throttled requests</figcaption></figure><p>Bear in mind that whereas read request throttling in GSI does not affect the main table, <a href="https://aws.amazon.com/premiumsupport/knowledge-center/dynamodb-gsi-throttling-table/">write requests throttling <em>does</em></a> as it fails the writes on the main table too!</p><h4>Lessons learned</h4><ul><li>Try distributing <em>all </em>your partition keys evenly, including the main table and all its GSIs.</li><li>While designing a data model, always verify your GSIs for “hot” partition problems. Consider throughput limits for both reads <br>(3000 RCU/s) and writes (1000 WCU/s).</li><li>If your key space is small, consider adding artificial <a href="https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-partition-key-sharding.html">suffixes</a> to expand the possible set of values.</li><li>Insufficient write capacity in a GSI (throttled <em>writes</em>) causes failures on writes in the main table and any of its GSIs.</li><li>Insufficient read capacity in a GSI (throttled <em>reads</em>) does not affect the main table or other GSIs.</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=cc7687d4b3bf" width="1" height="1" alt=""><hr><p><a href="https://codeburst.io/dynamodb-mistakes-we-made-so-you-dont-have-to-cc7687d4b3bf">DynamoDB mistakes we made (so you don’t have to)</a> was originally published in <a href="https://codeburst.io/">codeburst</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[You Are as Good as the People Around You]]></title>
            <link>https://medium.com/geekculture/you-are-as-good-as-the-people-around-you-b3cd6298dde6?source=rss-e63e806fd875------2</link>
            <guid isPermaLink="false">https://medium.com/p/b3cd6298dde6</guid>
            <category><![CDATA[recruitment]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[organizational-culture]]></category>
            <dc:creator><![CDATA[Tom Muc]]></dc:creator>
            <pubDate>Sun, 05 Dec 2021 19:48:56 GMT</pubDate>
            <atom:updated>2021-12-21T15:53:08.530Z</atom:updated>
            <content:encoded><![CDATA[<h4>and what it means for a senior developer</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*IjPfetTcLzls2k43CaRRrg.png" /></figure><h3>Good people attract good people</h3><p>Tom DeMarco and Tim Lister described some interesting observations about productivity in their great book <em>“Peopleware: Productive Projects and Teams”. </em>Long story short<em>, </em>they created <em>Coding War Games — </em>a<em> </em>benchmark<em> </em>consisting of a set of tasks to quantify the productivity levels of programmers from different companies. From 1984 to 1986 they verified 600+ developers from almost 100 companies. Even though they conducted their experiment 35 years ago, I believe their results are still valid.</p><p>In their findings, they mention so-called <em>10x developers — </em>people that are so productive that they outperform the worst developer by <em>10x factor </em>and median performer by <em>2.5x factor</em>. Perhaps they don’t necessarily produce 10x more <em>code</em> than the other developers these days, but bring value in other ways.</p><p>I bet you can easily name a few <em>10x developers</em> you’ve worked with. Think of the guys that were always sent out to talk to the business, solve the hardest problems, or develop code of the highest quality or importance. Or the ones that represent your team or organisation in the outside world, sharing their skills and knowledge. In short — they are the ones that other developers look up to.</p><p>Tom DeMarco and Tim Lister made one more interesting observation though. It turns out that the <em>10x productivity factor </em>is visible not only on an <em>individual level</em> but also at <em>the company level</em>. It leads to a simple conclusion:</p><blockquote><em>Good people attract good people</em>.</blockquote><p>If you doubt it, ask yourself:</p><blockquote>Would you rather be the best developer among mediocre ones or the mediocre one among the best ones?</blockquote><p>There is harsh truth behind this question — whenever you find yourself as the best programmer around it means you have little chance to learn anything new from other people at your organisation. If you are ambitious and keen on learning you can:</p><ul><li>start searching for a new position or a job,</li><li>sharpen your skills using external resources: online courses, conferences, side-projects, and so on,</li><li>or make people around you better…</li></ul><h3>Is this what senior devs do?</h3><p>A simple truth I’ve learned over the years is that software development is <em>a team sport</em> and playing alone won’t get you far. Self-centred programmers might be great when it comes to technicalities, but usually fail when faced with <em>sociological</em> problems — gathering the requirements, communication with the business, cooperation between teams.</p><p>Being a part of a great team, makes it easier to deliver value, is very rewarding, and simply makes your work more fun. I consider myself lucky — most of the programmers I work with are aware of the importance of team play. What I find not so common though are experienced developers ensuring that people around them become better over time. In my opinion, it’s one of the greatest qualities of <em>seniority</em>.</p><p>Some senior developers may wonder: why bother with the development of my colleagues when I’m always busy building business value by making new features or learning new skills anyway? Isn’t it a waste of my (<em>precious</em>) time?</p><p>Edmond Lau in his book <em>“The Effective Engineer” </em>answers this question with a graphic example. Imagine a tide that represents the level of skills within your organisation. The higher it gets the more successful the company becomes. If you — a senior developer — invest enough in the development of the people around you, you might soon find yourself carried away by the waves.</p><h3>What now? Recruit, recruit a lot</h3><p>Some things you can do as a senior developer to help people around you are obvious: pair programming, performing code reviews, onboarding newcomers, conducting workshops or presentations. What I find quite uncommon though is getting yourself involved in the recruitment process.</p><p>It might not seem like the best use of time as there are so many things to do instead — features to deliver, bugs to fix, design to do, discussions to raise, and so on. Why should recruitment be a priority? Remember the story of a tide? Taking a part in the recruitment process allows you to <em>actively</em> shape the level of programmers within your organisation. After all, if you want to work with the best, why don’t you recruit them <em>yourself</em>?</p><p>Think about it as a high-leverage activity — in case of a successful hire the few hours you spent on a recruitment session and writing feedback may become <em>2000+ </em>hours for your organisation. Even if you include all the sessions you attended that did not conclude with a new hire it’s still <em>tens</em> versus <em>thousands</em> of hours.</p><p>What’s more, being a recruiter will help you keep your skills in shape. While working on your everyday tasks you might not need some of the Computer Science concepts, or perhaps use only a subset of functions in your favourite programming language or framework. Running a recruitment session will be your chance to refresh and challenge your knowledge.</p><h3>Wrap up</h3><p>As a senior programmer, your teammates and their skills are almost as important as your own development. Don’t stop at the team level though, but get involved in the recruitment process to shape your whole organisation. And then… get carried away by the waves.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b3cd6298dde6" width="1" height="1" alt=""><hr><p><a href="https://medium.com/geekculture/you-are-as-good-as-the-people-around-you-b3cd6298dde6">You Are as Good as the People Around You</a> was originally published in <a href="https://medium.com/geekculture">Geek Culture</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[NewRelic One & Spring’s @Async]]></title>
            <link>https://medium.com/@tommuc/newrelic-one-springs-async-d68b48952c15?source=rss-e63e806fd875------2</link>
            <guid isPermaLink="false">https://medium.com/p/d68b48952c15</guid>
            <category><![CDATA[java]]></category>
            <category><![CDATA[microservices]]></category>
            <category><![CDATA[new-relic]]></category>
            <category><![CDATA[monitoring]]></category>
            <category><![CDATA[spring]]></category>
            <dc:creator><![CDATA[Tom Muc]]></dc:creator>
            <pubDate>Wed, 08 Sep 2021 18:23:46 GMT</pubDate>
            <atom:updated>2021-09-08T18:23:46.123Z</atom:updated>
            <content:encoded><![CDATA[<h4>A quick guide on how to include async calls details in NewRelic transaction traces in Spring-based application</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*T9iBKQDTKWdq2CIPVrcPxQ.jpeg" /></figure><h3>NewRelic introduction</h3><p><a href="https://newrelic.com/platform">NewRelic One</a> is, in simple terms, an observability platform that allows you to monitor different aspects of your distributed system and then define dashboards and alerting rules around them. For Java application monitoring there’s a dedicated <a href="https://docs.newrelic.com/docs/agents/java-agent/">Java Agent</a>, that enables code instrumentation and thorough monitoring of your service.</p><p>One particularly useful feature is <em>transaction monitoring.</em> A <a href="https://docs.newrelic.com/docs/apm/transactions/intro-transactions/transactions-new-relic-apm/"><em>transaction</em></a> is defined in NewRelic terms as “<em>one logical unit of work in a software application”. </em>In a microservice architecture, you can think of a single HTTP request processing or a topic/queue message processing. Each transaction is divided into <a href="https://docs.newrelic.com/docs/apm/transactions/intro-transactions/transactions-new-relic-apm/#segments"><em>segments</em></a>, each <em>segment</em> typically represents a function call that can be synchronous or asynchronous.</p><h3>Spring’s @Async annotation</h3><p>Among many useful things, Spring provides an easy way to execute operations asynchronously using <a href="https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/scheduling/annotation/Async.html">@Async</a> annotation. Without going too much into the details, it is usually used to run heavy operations in the background and wait for their results via Java’s Future, or to run some fire-and-forget kind of logic when you’re not interested in getting the result back.</p><h3>Async transaction segments monitoring</h3><p>To let NewRelic know about the asynchronous part of your code running in a different thread than the one that started the <em>transaction</em>, you need to:</p><ul><li>annotate your method with @Trace(async=true)</li><li>provide a Token object to it, and call link() or linkAndExpire()</li></ul><p>A simple example looks like this:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/14731611f553f9f49a64da64fb81d6c4/href">https://medium.com/media/14731611f553f9f49a64da64fb81d6c4/href</a></iframe><p>In the example above the @Trace annotation on SomeBusinessService&#39;s someOperation() ensures that NewRelic traces the execution of this method as a <em>transaction. </em>Please note that NewRelic’s Java Agent integrates well with popular frameworks, including SpringBoot, so typically there’s no need to use @Trace i.e. for code execution triggered as a part of HTTP request processing from @RestController.</p><h4>Task decoration time!</h4><p>How about using yet another useful approach from Spring and introduce a <a href="https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/core/task/TaskDecorator.html">TaskDecorator</a>to hide the complexity of NewRelic’s token linking?</p><p>Sounds simple, but the details matter. Refactoring the example from above, the implementation looks like this:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/379379927ada7833fea177c57c44ea30/href">https://medium.com/media/379379927ada7833fea177c57c44ea30/href</a></iframe><p>But it doesn’t work and there’s no trace of the async transaction segment in NewRelic — <em>why is that?</em></p><p>Long story short, the Token‘s link() (or linkAndExpire()) method must be called <a href="https://discuss.newrelic.com/t/spring-boot-async-and-trace/58528/5"><em>within</em> a method instrumented with</a><a href="https://discuss.newrelic.com/t/spring-boot-async-and-trace/58528/5">@Trace(async=true)</a>, or NewRelic will <em>ignore it!</em></p><p>In the example above the instrumented code will be executed in line #45, when the runnable is run, but we’re linking the token earlier. Hence NewRelic agent simply ignores the fact we just called linkAndExpire(). To fix it, we can consider a slightly different implementation of NewRelicTaskDecorator:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/b88f2a5975724280fed8a8d2659ee859/href">https://medium.com/media/b88f2a5975724280fed8a8d2659ee859/href</a></iframe><p>Notice there’s no need for Trace(async = true) annotation on SomeOtherService‘s someHeaveComputation() method anymore — we’re instrumenting the decorator logic instead.</p><h3>Wrap up</h3><p>The monitoring of asynchronous calls within your Spring-based Java microservice using NewRelic might be tricky, but when done right you’ll benefit from:</p><ul><li>the deeper insight into how your application behaves under the hood,</li><li>and a possibility to include additional details or report errors for the main NewRelic transaction.</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d68b48952c15" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Gradle Plugin Customisation — Lazy Properties]]></title>
            <link>https://codeburst.io/gradle-plugin-customisation-lazy-properties-e91691918173?source=rss-e63e806fd875------2</link>
            <guid isPermaLink="false">https://medium.com/p/e91691918173</guid>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[gradle]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[build]]></category>
            <dc:creator><![CDATA[Tom Muc]]></dc:creator>
            <pubDate>Wed, 31 Mar 2021 14:38:24 GMT</pubDate>
            <atom:updated>2021-04-01T12:10:56.225Z</atom:updated>
            <content:encoded><![CDATA[<h3>Gradle Plugin Customisation — Lazy Properties</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*C1Q4QSXL37h0N16eNpy5ig.png" /></figure><p>Ever got stuck with undefined properties when making your Gradle plugin customisable? Easy configuration and sensible defaults are crucial for a good user experience, but also a bit tricky to get right. Let’s explore how lazy properties can help.</p><h3>The Basics</h3><p>A good custom Gradle plugin usually comes with <a href="https://docs.gradle.org/current/userguide/custom_plugins.html#sec:getting_input_from_the_build"><em>an extension</em></a> that defines a way to configure it — either using properties or with a bit more sophisticated domain-specific language for it. The extension, well, extends Gradle’s domain-specific language, so that your users can include your plugin into their build.gradle just as any other configuration section.</p><p>To provide a great user experience Gradle plugins typically follow a <a href="https://docs.gradle.org/current/userguide/designing_gradle_plugins.html#convention_over_configuration"><em>convention-over-configuration</em></a> approach, meaning they come with some sensible defaults, but allow users to change the predefined values whenever they want.</p><h3>The Problem</h3><p>Let’s assume I am about to create a <em>Versioning plugin</em>, that prints the current version of a project in the console, and uses project.version attribute as a default value for our users’ convenience.</p><p>A naive approach for creating this plugin with a custom extension would look like this:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/3ad9eea4821691aa51eab43cdb7e785d/href">https://medium.com/media/3ad9eea4821691aa51eab43cdb7e785d/href</a></iframe><p>Assuming I applied my custom plugin in build.gradle as follows:</p><pre>plugins {<br>    id(&#39;tm.gradle.versioning&#39;)<br>}<br><br>project.version = &#39;1.1.1&#39;</pre><p>Now, running the gradle showVersion command will produce the following output:</p><pre>Current version: unspecified</pre><h4>What’s wrong?</h4><p>Let me briefly revisit the <a href="https://docs.gradle.org/current/userguide/build_lifecycle.html#sec:build_phases">three phases of a Gradle build</a> first:</p><p>❶ <em>Initialization</em> — Gradle goes through the settings.gradle file to determine whether it’s a single or multi-project build. Then it creates an Project instance for each identified project.</p><p>❷ <em>Configuration — </em>Gradle executes build.gradle files as scripts against the Project instances created in the initialization phase. Then it builds a directed acyclic graph of task objects but <em>doesn&#39;t execute them </em>yet. By default, the configuration of all projects happens before any task is executed.</p><p>❸ <em>Execution —</em> For each task specified via the command line, Gradle identifies its dependencies in a graph of task objects, and then executes it.</p><p>Back to my little plugin example, you can see the three different phases in the (simplified) build execution output:</p><pre>❶ Starting Build<br>Compiling settings file &#39;.../settings.gradle&#39;<br>Settings evaluated using settings file<br>Projects loaded. Root project using build file &#39;.../build.gradle&#39;</pre><pre>❷ &gt; Configure project :<br>Evaluating root project ... using build file &#39;.../build.gradle&#39;.</pre><pre><strong>ShowVersionExtension instance created<br>Plugin task registered<br>Project.version set to 1.1.1</strong></pre><pre>All projects evaluated.<br>...</pre><pre>❸ Tasks to be executed: [task &#39;:changeVersion&#39;, task &#39;:showVersionFromExtension&#39;]<br>&gt; Task :changeVersion<br>...</pre><p>Additional logging (marked as bold), included in build.gradle, extension and plugin implementation classes, reveals the issue with the naive approach — the ShowVersionExtension instance is created <em>before </em>the project.version property is set!</p><h3>The Solution — Lazy Properties!</h3><p>What does <em>lazy property </em>mean? Lazy properties have their value calculated in a delayed manner until it’s needed. In other words, they are not evaluated before it’s really required.</p><h4>Closure Time</h4><p>Let’s start with a historical (aka <em>outdated</em>) approach using Closure&lt;Object&gt;<em> </em>instead of a simple Object class field in ShowVersionExtension:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/3ddfe5c9d209ea4d951179a609e60f12/href">https://medium.com/media/3ddfe5c9d209ea4d951179a609e60f12/href</a></iframe><p><em>Side note, </em>notice the convenience setter to make it easier for your clients to set the value themselves.</p><p>Having introduced a closure, running the gradle showVersion command will produce the expected output:</p><pre>Current version: 1.1.1</pre><p>But wait, there’s more! Consider the following example of build.gradle with the changeVersion task, which is mimicking the logic around project.version that could be a part of some other plugin or your build.</p><pre>plugins {<br>    id(&#39;tm.gradle.versioning&#39;)<br>}<br><br>project.version = &#39;1.1.1&#39;<br><br><strong>tasks.register(&#39;changeVersion&#39;){<br>    doLast{<br>        project.version = &#39;2.2.2&#39;<br>    }<br>}</strong></pre><p>Running the gradle changeVersion showVersion command produces the following output:</p><pre>Current version: 2.2.2</pre><p>The closure evaluation is lazy enough so that I can get the latest project.version value set, even though it was modified by some other plugin or as a part of build.gradle script.</p><h4>Property and Provider</h4><p>Closures work just fine, but it’s been a while since Gradle 4.0 has introduced a better mechanism to handle lazy properties — the <a href="https://docs.gradle.org/current/javadoc/org/gradle/api/provider/Property.html">Property</a> and <a href="https://docs.gradle.org/current/javadoc/org/gradle/api/provider/Provider.html">Provider</a> interfaces.</p><p>In short, the Property represents a value that can be read and changed, whereas the Provider represents a value that can only be read. Typically you define configurable properties of a custom plugin using Property and utilize Provider for any values <em>derived </em>from them.</p><p>Back to my example, let’s examine how to use Property and Provider in ShowVersionExtension:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/d2fb2303808e87ca56a9fa9de2c53079/href">https://medium.com/media/d2fb2303808e87ca56a9fa9de2c53079/href</a></iframe><p>In the example above I define a configurable, lazy property of Object type, with a predefined value from project.version configured in the convention(...) method. Remember <em>the convention-over-configuration</em> approach? It’s here — stated explicitly using Property&#39;s API.</p><p>It’s exactly what I’ve been looking for— a sensible default value that users might use out of the box, as a well-defined convention, rather than setting up the property value themselves.</p><h3>Wrap up</h3><p>Making your custom Gradle plugin configurable is usually expected by your users. However, they don’t want to configure <em>everything</em> from scratch, but rather follow some well-established conventions if there are any. Ideally, your plugin should be usable out of the box — lazy properties defined using the Property and Provider will help you achieve that.</p><h3>Further reading</h3><p>There is a lot more to cover about Property and Provider interfaces — how to create, transform or read them, how to handle files or inputs/outputs from other tasks, and so on. The Gradle documentation has it all nicely described, make sure you don’t miss it.</p><p><a href="https://docs.gradle.org/current/userguide/lazy_configuration.html">Lazy Configuration</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e91691918173" width="1" height="1" alt=""><hr><p><a href="https://codeburst.io/gradle-plugin-customisation-lazy-properties-e91691918173">Gradle Plugin Customisation — Lazy Properties</a> was originally published in <a href="https://codeburst.io/">codeburst</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Pending Pacts — What Are They Exactly?]]></title>
            <link>https://codeburst.io/pending-pacts-what-are-they-exactly-8f047e5133cf?source=rss-e63e806fd875------2</link>
            <guid isPermaLink="false">https://medium.com/p/8f047e5133cf</guid>
            <category><![CDATA[contract-testing]]></category>
            <category><![CDATA[java]]></category>
            <category><![CDATA[microservices]]></category>
            <category><![CDATA[pact]]></category>
            <category><![CDATA[testing-micoservices]]></category>
            <dc:creator><![CDATA[Tom Muc]]></dc:creator>
            <pubDate>Thu, 11 Feb 2021 05:30:55 GMT</pubDate>
            <atom:updated>2021-04-12T14:49:46.393Z</atom:updated>
            <content:encoded><![CDATA[<h3>Pending Pacts — What Are They Exactly?</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*AfEY-i3CUvht_Tbtob6kXw.png" /></figure><p>Are you an API provider with builds occasionally failing on pact contracts verification?</p><p>You must learn about pending pacts!</p><h3>What’s the issue<em>?</em></h3><p>Assuming that you have an already established contract between a provider and consumer, there’re two possible scenarios when its verification may start failing:</p><ol><li>The provider implementation changes</li><li>The contract changes</li></ol><p>The first one is straightforward — it’s a scenario where the provider introduces code changes that break the backward compatibility of an existing API.</p><p>The second one, however, is a great problem of Pact workflow — a change to the contract made by a consumer may cause build failures on the provider side. Let me say it once again — a change made to the contract by an API customer, in their own codebase, may harm the providers’ builds.</p><p>What kind of changes are problematic? It could be as simple as defining contracts with incorrect value examples that cannot be used on the provider side, or wrong assumptions about the provider state. But apart from silly mistakes, there’s a more common scenario — consumers may work in an ATDD-kind-of way, defining and publishing new expectations in a contract (i.e. requiring breaking changes or another API version) even before the provider can fulfil them.</p><p>Luckily, there’s a solution for this — it’s pending pacts!</p><h3>What is a pending pact?</h3><p>A pending pact is a contract that can be verified by the provider without failing the overall verification phase of his build even if there are some mismatches found. You may wonder how is it different from simply ignoring all the mismatches? It is, as failed verification results are still published to the Pact Broker — it’s an important source of feedback for the consumer side.</p><p><em>Side note: You must verify all the interactions to publish the verification results to the Pact Broker — be careful with </em><a href="https://docs.pact.io/implementation_guides/jvm/provider/junit/#interaction-filtering"><em>interaction filtering</em></a><em>!</em></p><p>And just to make it clear, as a consumer you don’t need to do anything to mark your pact version as a pending one. It’s a property that’s calculated by the Pact Broker during the provider’s contract verification tests execution. In order to determine the pending<em> </em>state of a contract the Pact Broker uses:</p><ul><li>The content of a contract (also known as a <em>pact version)</em></li><li>The provider’s branch name configured for the verification task</li></ul><p>Please note that the pending pacts feature applies to <a href="https://docs.pact.io/pact_nirvana/step_4#d-configure-pact-to-be-verified-when-provider-changes">provider changed workflow</a>, where the provider gets contracts to verify from the Pact Broker, but not to <a href="https://docs.pact.io/pact_nirvana/step_4/#e-configure-pact-to-be-verified-when-contract-changes">contract changed workflow</a> based on webhooks.</p><h4>Pending pacts and backward compatibility</h4><p>There’s an important aspect of pending pacts —they can stop being considered as pending! How is that possible? <a href="https://docs.pact.io/pact_broker/advanced_topics/pending_pacts/#to-start-using-the-pending-pacts-feature">Pact’s documentation</a> explains it nicely:</p><blockquote>The purpose of the pending flag is to ensure that provider builds are not broken by changes that were introduced by the consumer, but to also ensure that backwards compatibility is maintained when a change is introduced by a provider. It achieves this by treating the first successful verification of a pact version <strong>by a particular branch of the provider</strong> as an <strong>implicit acceptance of the contract</strong>.</blockquote><p>There are two important things to note here:</p><ul><li>Once the provider accepts the contract — meaning it manages to fulfil all the expectations and successfully verifies against the contract — any changes introduced later must maintain backward compatibility. This means that if ever the verification fails again, it’d be due to the provider’s fault.</li><li>The pending state of a pact is dependent on the provider’s branch, or rather, versioning. This means that given contract content — a<em> pact version </em>— may be <em>accepted</em>, and no longer <em>pending</em>, for one <em>provider version</em> (i.e. a feature branch), but not for another (i.e. the main branch).</li></ul><h3>How to use the pending pacts feature?</h3><p>In order to make it work you need two compatible ingredients — a pact library and the Pact Broker that support the pending pacts feature. In the JVM world of pacts the requirements are as follows:</p><ul><li><a href="https://docs.pact.io/implementation_guides/jvm/provider/junit/#pending-pact-support-version-413-and-later">JUnit provider: 4.1.3+</a></li><li><a href="https://docs.pact.io/implementation_guides/jvm/provider/junit/#pending-pact-support-version-413-and-later">PactBroker: 2.60.0+</a></li></ul><p>When it comes to the configuration of JUnit-based verification tests, it is as simple as:</p><pre>@PactBroker(<br>  host = &quot;&lt;your_pact_broker_host&gt;&quot;,<br>  port = &quot;&lt;your_pact_broker_port&quot;,<br><strong>  enablePendingPacts=&quot;true&quot;,<br>  providerTags = &quot;MAIN&quot;)</strong></pre><h4><strong>What is providerTag for?</strong></h4><p>As mentioned earlier, the Pact Broker needs the provider’s branch name to evaluate the pending state of a contract dynamically — the providerTag property defines which tag will be used for this.</p><p>Typically any changes to the provider’s API are implemented on a dedicated feature branch. Let’s say you finally fulfilled the new expectations on a feature branch called some-feature, ran your contract verification tests and published the successful results to the Pact Broker. If the providerTag wasn’t taken into consideration, this would remove the pending status of a contract for the main branch too, and effectively break builds there.</p><h3>How does it work — step by step</h3><p>❶ There’s a well-established contract between Some Consumer (version 1.0.0) and Some Provider (version 5.1.0), describing a simple /hello API that’s been working on PROD environment for some time now.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/660/1*mw7H8df9Nr_-lPQ3fwaB5w.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/675/1*JEc_aXueorqGu2uEANkE3g.png" /><figcaption>Request and response of a simple API between Some Consumer and Some Provider</figcaption></figure><p>❷ Some Consumer team develops a new feature that requires the additionalfarewell field in the response from Some Provider.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/660/1*mw7H8df9Nr_-lPQ3fwaB5w.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/676/1*RE9XzXAXs_AUOB6eqHu2cQ.png" /><figcaption>Request and response of a simple API between Some Consumer and Some Provider after changes</figcaption></figure><p>Some Consumer merges its feature branch and publishes the new contract version to the Pact Broker:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*j14GMPLHEUoAHWsaMjwUpw.png" /></figure><p>❸ In the meanwhile, Some Provider may develop some other, unrelated feature and trigger a build for the newest5.1.0 version on his main branch. This time though, the contract verification tests fail.</p><pre>BodyMismatch: $ BodyMismatch: $ Expected farewell=&#39;Bye Tom!&#39; but was missing</pre><pre>{<br>        -  &quot;greeting&quot;: &quot;Hello Tom!&quot;,<br>        -  &quot;farewell&quot;: &quot;Bye Tom!&quot;<br>        +  &quot;greeting&quot;: &quot;Hello Tom!&quot;<br>        }</pre><p>❹ This is the exact problem pending pacts were introduced for! Some Provider re-runs contract verification tests with the pending pacts feature enabled. His builds don’t fail anymore, and the console log sheds some light on the pact verification:</p><pre>Verifying a pact between Some Consumer (1.1.0) and Some Provider [<strong>PENDING</strong>]</pre><pre>Notices:<br>    1) The pact at <a href="http://localhost/pacts/provider/Some%20Provider/consumer/Some%20Consumer/pact-version/df628286a2d16ed21b53b4fd4e1acea9446d7c9c">http://localhost/pacts/provider/Some%20Provider/consumer/Some%20Consumer/pact-version/df628286a2d16ed21b53b4fd4e1acea9446d7c9c</a> is being verified because it matches the following configured selection criterion: latest pact between a consumer and Some Provider<br>    2) <strong>This pact is in pending state for this version of Some Provider because a successful verification result for a version of Some Provider with tag &#39;MAIN&#39; has not yet been published. </strong>If this verification fails, it will not cause the overall build to fail. Read more at <a href="https://pact.io/pending">https://pact.io/pending</a></pre><p>Some Provider publishes the failed verification results to the Pact Broker — it’s a way to let know the consumer that their newly created contract cannot be fulfilled yet. Notice the red verification status below:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*hXdkGu3N6MHGUV2i0W9iIg.png" /></figure><p>❺ The failed verification results are crucial because they will prevent Some Consumer from deploying to PROD up until there’s a compatible provider version available and verified.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*NiicXizRNxIdjcvR5nBGRQ.png" /></figure><p>❻ Some Provider implements changes to include thefarewell field in his response on a feature branch called farewell-api. Once the contract verification tests pass it publishes the results to the Pact Broker.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*AYI0_EjllP5EjJi8gdEqog.png" /></figure><p>Does it mean the main branch tests will also pass the verification now? No, not really. The verification on the main branch still fails at that point. That’s because of the providerTag=MAIN specified when enabling the pending pacts feature. It prevents the feature branch verification results from being mistakenly taken as valid for the MAIN tag too.</p><p>To successfully verify the main branch, the feature branch farewell-api needs to be merged first, and then the verification and tagging must be triggered once again.</p><p>❼ Some Provider merges farewell-api branch to the main branch, creating a new 5.2.0version, and runs contract verification tests. Their successful results are published to the Pact Broker.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*MCCF93B3ONVvpR5b7JSBxg.png" /></figure><p>❽ Some Consumer can now safely deploy to PROD, yay!</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*uJtscuhrCz0nMXbeU0jLbw.png" /></figure><h3>Wrap up</h3><p>The <em>pending</em> pact feature is somewhat difficult to understand, mainly because of the dynamic nature of pacts’ state. However, using it is crucial if your provider’s APIs are really <em>consumer-driven — </em>meaning your consumers define their expectations way sooner than you could fulfil them.</p><h4>Further reading</h4><ul><li><a href="http://blog.pact.io/2020/02/24/how-we-have-fixed-the-biggest-problem-with-the-pact-workflow/">How we&#39;ve fixed the biggest problem with the Pact workflow</a></li><li><a href="http://blog.pact.io/2020/02/24/introducing-wip-pacts/">Introducing WIP Pacts</a></li><li><a href="https://docs.pact.io/pact_broker/advanced_topics/pending_pacts/">Pending pacts | Pact Docs</a></li><li><a href="https://docs.pactflow.io/docs/workshops/ci-cd/workshop/protecting-the-provider/">Protecting provider builds from changed pacts | Pactflow Documentation</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=8f047e5133cf" width="1" height="1" alt=""><hr><p><a href="https://codeburst.io/pending-pacts-what-are-they-exactly-8f047e5133cf">Pending Pacts — What Are They Exactly?</a> was originally published in <a href="https://codeburst.io/">codeburst</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The Basics of Contract Tests]]></title>
            <link>https://codeburst.io/the-basics-of-contract-tests-920ff363c820?source=rss-e63e806fd875------2</link>
            <guid isPermaLink="false">https://medium.com/p/920ff363c820</guid>
            <category><![CDATA[contracts]]></category>
            <category><![CDATA[testing-micoservices]]></category>
            <category><![CDATA[testing]]></category>
            <category><![CDATA[contract-testing]]></category>
            <category><![CDATA[consumer-driven-contract]]></category>
            <dc:creator><![CDATA[Tom Muc]]></dc:creator>
            <pubDate>Thu, 14 Jan 2021 04:22:08 GMT</pubDate>
            <atom:updated>2021-01-18T08:00:47.496Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="A drawing of a handshake with a contract document in the background" src="https://cdn-images-1.medium.com/max/1024/1*2SkKVL6gdIF4Z34AdoKwJQ.jpeg" /></figure><p>Have you ever verified your integration with an external service using a mocked response, only to realize later that things work quite differently in a production environment? If only you knew some approach to ensure mocks are just fine and up to date, right?</p><p>Contract testing to the rescue!</p><h3>Introduction</h3><p>Distributed systems these days are complex, there’s no doubt about that. With more and more moving parts — new services being created, old services being deprecated, new API versions published, or existing API versions being extended — it’s difficult to keep up with the changes. It becomes especially tedious to ensure that all test doubles (mocks) reflect the actual behavior of the API of external services that you depend on.</p><p>Contract testing is a technique that might help you ease the pain. In a nutshell, it’s an approach to testing the integration between two parties — a provider and a consumer — in isolation. Each side must ensure it fulfills the agreed requirements written in a contract. Typically the integration is either an HTTP request/response communication or some kind of messaging.</p><p>The idea of verifying API contracts isn’t new — you can easily find <a href="https://martinfowler.com/bliki/ContractTest.html">articles dating back to 2011</a>, or <a href="https://martinfowler.com/articles/consumerDrivenContracts.html">even older</a>, mentioning this approach. However, nowadays contract testing is gathering more and more popularity in the world struggling with the integration of an ever-growing number of microservices.</p><h4>Contract tests nomenclature</h4><p>Before going any further let’s establish an understanding of common nomenclature used for contract tests.</p><ul><li><em>a contract — </em>a document that defines the expected structure of an AP: request, response, path, query parameters, headers, etc. Usually written in a text file in a specific format, depending on the technology used.</li><li><em>a consumer — </em>a side of a contract that consumes, or simply uses a given API. Sometimes referred to as <em>a client.</em></li><li><em>a provider</em> — a side of a contract that provides, or simply owns a given API. Sometimes referred to as <em>a serve</em>r.</li></ul><h3>Provider-driven contract testing</h3><p>In a provider-driven approach, it’s the provider that drives the process of API evolution, publishing new contracts (and associated test doubles) whenever there’s a significant change to it. A typical flow of actions looks as follows:</p><ol><li>The provider defines a contract in his codebase</li><li>The provider runs a build and tests to ensure the contract is fulfilled</li><li>If tests pass the provider publishes a contract and associated test doubles (i.e. WireMock mappings) into an artifact repository</li><li>When the consumer runs his build, it gets the latest test doubles published by the provider and runs some in-memory HTTP server to mock the provider</li><li>Then the consumer may run tests to verify the integration with the provider</li></ol><p>The contracts’ purpose is to ensure the provider implementation fulfills the request/response specification <em>completely</em>, regardless of the fact if his clients use all or just a subset of data in a response. Or to put it in a simpler way, the provider defines a <em>here-is-what-I-can-do </em>kind of contract for his clients, and it’s up to them to pick whatever is interesting for them.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*r85tkdz7UiSZJWpErgHGsw.png" /><figcaption>Provider-driven created stubs vs. client needs</figcaption></figure><p><em>The provider publishes a response stub including all the fields available in </em><em>/v1/person/{id} API (❶). However, the needs of each client are different — Consumer A requires </em><em>id and </em><em>name(❷), Consumer B uses only</em><em>age (❸), and Consumer C needs all of the fields (❹).</em></p><h4>Pros</h4><p>The provider-driven approach to contract testing leaves full control of the evolution of the API to the provider, meaning he can publish the new endpoint versions, or select the naming by himself. That’s quite useful if you’re in a team that develops a provider service with a well-defined business domain, as it’s usually <em>you</em>, not your clients, that know the upcoming new features and their impact on the API first.</p><p>This approach is also well-applicable for a provider that exposes a public API and can’t work closely with his clients. It enables new clients to get to know the capabilities of an API quickly just by looking at the published stubs.</p><h4>Cons</h4><p>On the other hand, as this approach pretty much ignores the consumer perspective, it has an obvious drawback — it doesn’t stop the provider from producing a <em>hard-to-use</em> API. It’s easy to fell into a trap of <em>assuming</em> how your clients perceive your domain, or what are their expectations towards your API.</p><p>Another downside of not knowing how your API is used by your clients is that whenever you want to deprecate or modify it in a breaking way, you must assume that <em>all your consumers</em> may need your <em>whole response. </em>Or, alternatively, ask around and double-check with each one of your clients — if only you know them all of course.</p><h3>Consumer-driven contract testing</h3><p>In a consumer-driven approach to contract testing, it’s the consumer that drives the changes to the provider’s API. What does it mean exactly? A typical flow of actions looks as follows:</p><ol><li>The consumer defines a contract in his codebase</li><li>The consumer publishes the contract into a dedicated contract repository (i.e. Pact Broker)</li><li>The provider gets notified about the new contract</li><li>The provider run tests that verify if all the requirements are met by firing consumer-defined requests against the provider API and checking if the responses match with consumer-defined responses</li><li>If tests pass the integration between the consumer and the provider is marked as verified</li></ol><p>Please note that, depending on the tool used, there are other possible ways to organize consumer-driven contract testing flow, i.e. have a look at <a href="https://cloud.spring.io/spring-cloud-contract/reference/html/using.html">Spring Cloud Contract</a> documentation for more details.</p><p>The contracts are focused on consumer <em>integrations</em> with the provider, rather than specifying the whole request/response structure. For a provider, it’s a valuable perspective — each of its clients defines exactly what fields they use, and which they simply ignore. Simply speaking, it’s the consumer that defines <em>here-is-what-I-need</em> kind of contract for the provider to fulfill.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*0Z-r--fMmaGgitnHUNumoA.png" /><figcaption>Clients’ needs driving the provider’s API design</figcaption></figure><p><em>All consumers define their needs separately — Consumer A requires </em><em>id and </em><em>name(❷), Consumer B uses only</em><em>age (❸), and Consumer C needs all of the fields (❹). Putting all the requirements together the Provider can see what needs to be provided in </em><em>/v1/person/{id} API and to whom.</em></p><p>Does it mean the provider is no longer in charge of his API and has to blindly follow all the requirements coming from all his clients? Not necessarily. It’s not that consumers have the final decision on everything, including naming or data structures. Instead, they define the <em>initial proposal</em> of changes, i.e. as a pull request in the consumer’s codebase, which should later be discussed involving both sides — a provider and a consumer. As a provider, it’s perfectly fine to disagree with the initial proposal, and suggest some changes — it’s your API after all. However, the important bit is the discussion itself which is usually an eye-opener. As a provider you get to know your client’s needs, you can see how they intend to use your service’s API, you can simply find out how they see your service from the outside world.</p><h4><strong>Pros</strong></h4><p>Using the consumer-driven approach to contract tests typically leads to better-designed APIs which are easier to use for the clients. From the provider perspective, the feedback loop on the quality of your API definition is much shorter as it involves the consumers as soon as at the design stage!</p><p>Additionally, the provider knows exactly which endpoints or fields from the response are actively used and required by its clients. It allows for lower maintenance costs, i.e. makes API/field deprecation easier — no more log scrapping or questionnaires send out to your clients to find out if anyone uses the abc field from your response. As a provider, you can simply run a set of tests against the contracts defined by your clients and get the answer immediately.</p><h4>Cons</h4><p>What are the drawbacks then? First of all, there’s no single view of all the capabilities of an API — they are scattered between different clients’ contracts. This, as opposed to the provider-driven approach, may put some additional effort to understand the full picture of the API on consumer teams aiming to start using it without prior knowledge.</p><p>Secondly, the client-specific tests on the provider side might be cumbersome to maintain if there’s no alignment on how to define your consumer-driven contracts. How is that possible? Consider the following example. Assuming the provider uses UUID as a type of the id field in his response DTO class and all his clients expect this field in their contracts. However, some of them specified it as UUID(with example value ofd8c203e1-987a-4e3d-9256-6c79982f5bd6), and others as String (with example value of this-is-some-id). The latter creates expectations about the response from the Provider that cannot be fulfilled and verified in his tests because of the way his DTOs are implemented, not the actual difference in the JSON structure. This is why it’s important to remember that creating contracts is supposed to be a collaboration between the consumer and provider, despite the fact that the actual code ends up in the consumer’s codebase.</p><h3>Wrap up</h3><p>There are two approaches to contract tests: provider-driven and consumer-driven. The final result — a verifiable contract between the consumer and provider and test doubles that are always up to date — is the same for both.</p><p><em>It’s the way we create them, the flow of communication, that differs.</em></p><p>Whatever approach you take remember that contracts should be created in close cooperation of both sides — the consumer and provider. Even the most comprehensive tools are not able to replace the discussion between the members of two teams. A well-defined contract that is up-to-date brings a lot of value to both parties, which makes them both responsible for it, no matter whose codebase actually contains the code describing it.</p><h4>Further reading</h4><ul><li><a href="https://martinfowler.com/bliki/ContractTest.html">bliki: ContractTest</a></li><li><a href="https://martinfowler.com/articles/consumerDrivenContracts.html">Consumer-Driven Contracts: A Service Evolution Pattern</a></li><li><a href="https://docs.pact.io/">Introduction | Pact Docs</a></li><li><a href="https://docs.spring.io/spring-cloud-contract/docs/2.2.4.RELEASE/reference/html/">Spring Cloud Contract Reference Documentation</a></li><li><a href="https://docs.pact.io/getting_started/comparisons/#how-does-pact-differ-from-spring-cloud-contract">Comparisons with other tools | Pact Docs</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=920ff363c820" width="1" height="1" alt=""><hr><p><a href="https://codeburst.io/the-basics-of-contract-tests-920ff363c820">The Basics of Contract Tests</a> was originally published in <a href="https://codeburst.io/">codeburst</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Pact Contracts in Deployment Pipelines]]></title>
            <link>https://codeburst.io/i-can-deploy-can-you-pact-contracts-in-deployment-pipelines-ec823f3ed544?source=rss-e63e806fd875------2</link>
            <guid isPermaLink="false">https://medium.com/p/ec823f3ed544</guid>
            <category><![CDATA[pact]]></category>
            <category><![CDATA[java]]></category>
            <category><![CDATA[deployment]]></category>
            <category><![CDATA[testing-micoservices]]></category>
            <category><![CDATA[contract-testing]]></category>
            <dc:creator><![CDATA[Tom Muc]]></dc:creator>
            <pubDate>Tue, 15 Dec 2020 18:49:31 GMT</pubDate>
            <atom:updated>2020-12-16T16:47:16.280Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Wm-q5o78rbL_Z1sSk8MY3w.jpeg" /></figure><p>Learn how to make the best out of contract testing by using Pact Broker and can-i-deploy tools in your build &amp; deployment pipelines.</p><h3>Pact Broker</h3><p>The <a href="https://github.com/pact-foundation/pact_broker">Pact Broker is an open-source</a> tool that allows you to share your pacts and store the results of their verification. You may treat it as a repository of your published contracts together with their testing report.</p><h4>Pact publishing</h4><p>In order to see your pact on Pact Broker pages, you need to publish it first. Pact contract testing follows the consumer-driven approach, which means it’s the consumer who creates a contract defining new requirements against the provider API.</p><p>As a part of her build — optionally for feature branches and, ideally, always for the main branch— the consumer runs tests that create pacts (i.e. using <a href="https://docs.pact.io/implementation_guides/jvm/consumer/groovy">Groovy DSL</a>), and later triggers their publication to Pact Broker.</p><p>You can use the following tools to publish a pact:</p><ul><li>pactPublish task provided by <a href="https://docs.pact.io/implementation_guides/jvm/provider/gradle/#publishing-pact-files-to-a-pact-broker">Pact Gradle plugin</a></li><li>pact-broker publish command from <a href="https://github.com/pact-foundation/pact-ruby-cli">Pact CLI</a></li></ul><h4>Pact verification</h4><p>It is the responsibility of the API provider to check if it fulfills all the needs of its consumers, based on pacts published by them to the Pact Broker. Depending on the approach the provider should run a dedicated suite of tests during every build on the main branch and publish their results to Pact Broker. Embedding such checks into all builds prevents the Provider from breaking the contracts with its consumers.</p><p>In order to verify pacts you can use, among others:</p><ul><li>pactVerify task provided by <a href="https://docs.pact.io/implementation_guides/jvm/provider/gradle#verifying-pact-files-from-a-pact-broker">Pact Gradle plugin</a></li><li>Pact’s dedicated test runners, including <a href="https://docs.pact.io/implementation_guides/jvm/provider/junit">JUnit 4</a>, <a href="https://docs.pact.io/implementation_guides/jvm/provider/junit5">JUnit 5</a>, <a href="https://docs.pact.io/implementation_guides/jvm/provider/scalatest">scalatest</a></li></ul><h4>Versioning</h4><p>Generally speaking the versioning of your application in Pact Broker should follow the same set of rules as the <a href="https://semver.org/">semantic versioning</a> approach we use for application artifacts.</p><p><a href="https://docs.pact.io/getting_started/versioning_in_the_pact_broker/#best-practices">Pact’s documentation</a> mentions some guidelines worth to know though:</p><ul><li>Ensure your application version changes whenever the contract requirements change or when there’s a new deployable artifact created. This is self-explanatory and goes well with semantic versioning.</li><li>Your application version should be unique. Because of that, I recommend using the branch name as a version when publishing contracts from a feature branch. Don’t use x.y.z-SNAPSHOT versioning, as it may lead to duplicates in Pact Broker when there are multiple feature branches developed at the same time.</li><li>Avoid using random data in your contracts. <em>This is very important</em>, because if you do, then every time you publish your pact it’ll be considered unique. As a result, Pact Broker will require you to verify each one separately rather than depend on its internal mechanism to detect duplicates (you’ll read more about this later).</li></ul><h4>Tagging</h4><p>Tags are simply string values assigned to the specific version of a <em>pacticipant </em>in Pact Broker. A <em>pacticipant </em>in Pact’s nomenclature is a participant of a contract — either a consumer or a provider. It’s important to note that tags <em>are not</em> assigned to pacts themselves.</p><p><strong>Some good tagging practices:</strong></p><ul><li>Tag it with the branch name indicating where the application version comes from. Typically it is going to be main, or master, but could also be dev or feature_branch_name if you want to check pacts which are under development.</li><li>Add the environment-specific tag when deploying your application, i.e. use dev, test, prod</li></ul><p><strong>Why even bother with tagging your consumer or provider versions?</strong></p><p>You can use tags to check different versions of a consumer and provider against each other in a specific context, i.e. while developing a new functionality on a branch, before merging your feature branch, or deploying your application to production. Ensuring the contract agreements between the consumer and provider, without a need to run additional integration tests is the essence of contract testing with Pact.</p><h3>Can I deploy or can-i-deploy?</h3><p>Have you ever wondered if you can deploy your application without interfering with your consumers? Or, from the other perspective, ever wondered if the provider you depend on has already published his new API, so that you could deploy your microservice and use it? If yes, then Pact’s tool named can-i-deploy is something you’ve been looking for!</p><p>Simply speaking, it allows you to check if a specific version of a consumer (or a producer) can be safely deployed to a given environment — meaning there’s a compatible version of producer (or a consumer) available there.</p><p>For instance, running the following CLI command might become a part of the deployment process of a consumer named “Some Consumer”, that checks if it’s safe to deploy to production (tagged as PROD).</p><pre>./pact-broker can-i-deploy --pacticipant &quot;Some Consumer&quot; --version 1.0.0 --to PROD -b localhost</pre><p>Please mind the parameter name is <em>pacticipant</em>, not participant!</p><h3>How it works in practice — step by step</h3><h4>Branch development</h4><p>It’s a good practice to publish Pacts from your feature branches when developing the consumer code. This allows the provider to get notified about upcoming requirements. Also, it prevents you from merging code that is about to fail because of a missing or incompatible provider.</p><p>The rule of thumb is to tag them with a branch name. You don’t want to use snapshot versioning (i.e. 1.0.0-SNAPSHOT), as it may be reused by a different feature branch developed in parallel. We don’t want to tag with git revision numbers either, as it’d flood our Pact Broker with new versions, one for every commit to your branch.</p><p>Another way to approach it is to make pact publishing on branches a manual step — ideally, run only once or twice, and only if pact verification is needed sooner.</p><p>Let’s see how it works.</p><p>❶ Some Consumer develops a feature on some_feature_branch and publishes a Pact. It appears in Pact Broker like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*SJQ8XjLjvR0wNosq_l1yEA.png" /></figure><p>❷ Some Provider verifies interactions with its consumers — i.e. in a dedicated verification job when triggered by a webhook from Pact Broker, or as a part of builds running on the main branch— and publishes the verification results for version 5.0.0, tagging it as MAIN. Pact Broker is updated as follows:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*EFbW3Y-0W0OkZMzOKjxvAg.png" /></figure><p>❸ As a part of a build of some_feature_branch (or simply before merging it to the main branch) Some Consumer may check if all of its requirements are met by Some Provider:</p><pre>./pact-broker can-i-deploy --pacticipant &quot;Some Consumer&quot; --version some_feature_branch --to MAIN -b localhost</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Hvxfvc17j8PYNmQxOQaQLw.png" /></figure><p>It’s ok! Some Consumer may now safely merge its feature branch to the main branch, release a new version — 1.0.0 — and tag it as MAIN in Pact Broker.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*RECJ-Ob-WsR9SYnFRO2CQA.png" /></figure><p>Notice that Pact Broker is instantly aware that it’s already been verified before by Some Provider, version 5.0.0. How is it possible? There’s a nice feature under the hood that detects duplicate pacts by using the comparison of hashes generated for the pact file. This eliminates a need for repeated verifications if the contract hasn’t changed. This, as you can see, is particularly useful when working with feature branches.</p><h4>Production deployments</h4><p>We now have Some Consumer and Some Provider with their changes merged to their main branch, released as 1.0.0, and 5.0.0, respectively. Both tagged as MAIN in Pact Broker.</p><p>We’re ready to deploy them to production, let’s see how it goes.</p><p>❶ Some Consumer checks if it can be safely deployed to production:</p><pre>./pact-broker can-i-deploy --pacticipant &quot;Some Consumer&quot; --version 1.0.0 --to PROD -b localhost</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*OtodSGGZnp_7OvmIeKppIg.png" /></figure><p>The answer is no — Some Provider hasn’t been deployed to production yet.</p><p>❷ Some Provider runs can-i-deploy tool to verify if it’s fine to deploy to production as a part of its deployment scripts:</p><pre>./pact-broker can-i-deploy --pacticipant &quot;Some Provider&quot; --version 5.0.0 --to PROD -b localhost</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*MORMDDhoDNHqhb3Q3LmPNg.png" /></figure><p>It’s fine, as the newest 5.0.0 version fulfills all the requirements defined in contracts involving Some Provider.</p><p>❸ Some Provider deploys version 5.0.0 to production and tags it as PROD in Pact Broker</p><pre>./pact-broker create-version-tag --pacticipant &quot;Some Provider&quot; --version 5.0.0 --tag PROD -b localhost</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ITTcY-DfD81coRvVMeW4Fw.png" /></figure><p>Pact Broker now shows PROD tag assigned to provider version5.0.0:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*F6Fg90uufva1Z1X4IqS0Yg.png" /></figure><p>❹ Some Consumer checks if it can be safely deployed to production again:</p><pre>./pact-broker can-i-deploy --pacticipant &quot;Some Consumer&quot; --version 1.0.0 --to PROD -b localhost</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ijoxLK_bE84nlUQCCXByCQ.png" /></figure><p>The computer says “yes, yay!” Some Provider is deployed to production with all the necessary changes already.</p><p>❺ Some Consumer deploys version 1.0.0 to production and tags it as PROD in Pact Broker:</p><pre>./pact-broker create-version-tag --pacticipant &quot;Some Consumer&quot; --version 1.0.0 --tag PROD -b localhost</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*9N2OqkxJNRy21xhs2dfh-A.png" /></figure><p>Pact Broker now shows PROD tag assigned to consumer version1.0.0:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*iFSKJwM5B08b-g8UBzH6yw.png" /></figure><h4>Rollback</h4><p>From time to time you might find yourself in a situation when you need to rollback the version you just deployed to production. How does it work with pacts, tags, and Pact Broker? Let’s find out.</p><p>❶ Some Provider deploys version 5.1.0 to production, tagging it as PROD in Pact Broker:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*sJJAwDDX1idBMBMcbTaG6A.png" /></figure><p>❷ Some Provider performs a rollback from version 5.1.0 to 5.0.0. After redeploy the PROD tag is still there, assigned to 5.1.0 in Pact Broker, just like in the previous step.</p><p>❸ Some Consumer checks if it can be safely deployed to production:</p><pre>./pact-broker can-i-deploy --pacticipant &quot;Some Consumer&quot; --version 1.0.0 --to PROD -b localhost</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*JLLuyQkd03OLzi6iXcvufQ.png" /></figure><p>Notice it is being verified against Some Provider version 5.1.0 which has just been rolled back to 5.0.0 on production.</p><p>❹ In order to make the tagging right, Some Provider must remove PROD tag from the rolled back version — 5.1.0. As currently the Pact CLI does not support this, the only way is to use the REST API:</p><pre>curl -X DELETE <a href="http://localhost/pacticipants/Some%20Provider/versions/5.1.0/tags/PROD">http://localhost/pacticipants/Some%20Provider/versions/5.1.0/tags/PROD</a></pre><p>Now Pact Broker tags reflect the production environment state — Some Provider runs 5.0.0 on production, and this version is correctly tagged asPROD, not 5.1.0 anymore:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*YVLNm3m4jr0SX9H8EO1yVQ.png" /></figure><p>❺ Some Consumer may now check if it can be deployed to production:</p><pre>./pact-broker can-i-deploy --pacticipant &quot;Some Consumer&quot; --version 1.0.0 --to PROD -b localhost</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*SKO4FVXUwyM6AwU4cXnp8A.png" /></figure><p>Now it gets verified against the correct 5.0.0 version of Some Provider as expected.</p><p><strong>Why is that?</strong></p><p>When using can-i-deploy Pact Broker selects the latest <em>pacticipant</em> version tagged as PRODfrom all the versions with this tag.<em> </em>It’s<em> not </em>the other way around — find the most recently created PROD tag, and then select the <em>pacticipant </em>version.</p><p>Because of that, whenever you perform a rollback you need to ensure that tags in Pact Broker reflect the actual state of your production. Otherwise your consumer (or your provider) might be impacted and use can-i-deploy to check her contracts against the wrong version, which may lead to incompatible deployments and failures on production.</p><h3>Wrap up</h3><p>Pact comes not only with convenient libraries to define your contracts and interactions, but also tools that help you enforce these agreements in your deployment pipelines. The usage of can-i-deploy in deployment pipelines is where Pact Broker and it’s tooling really shines.</p><p>They will save you a lot of time and effort required to ensure your microservices can communicate with each other. Forget about your bloated integration tests, running on a dedicated test environment just to verify you’ve got your DTOs mapping right on both sides —it’s time to <em>pact up</em>!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ec823f3ed544" width="1" height="1" alt=""><hr><p><a href="https://codeburst.io/i-can-deploy-can-you-pact-contracts-in-deployment-pipelines-ec823f3ed544">Pact Contracts in Deployment Pipelines</a> was originally published in <a href="https://codeburst.io/">codeburst</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Contract Tests With Pact JVM — The Tricky Parts]]></title>
            <link>https://medium.com/swlh/contract-tests-with-pact-jvm-the-tricky-parts-6b2fee5d139c?source=rss-e63e806fd875------2</link>
            <guid isPermaLink="false">https://medium.com/p/6b2fee5d139c</guid>
            <category><![CDATA[pact]]></category>
            <category><![CDATA[testing]]></category>
            <category><![CDATA[micoservices]]></category>
            <category><![CDATA[java]]></category>
            <category><![CDATA[contract-testing]]></category>
            <dc:creator><![CDATA[Tom Muc]]></dc:creator>
            <pubDate>Thu, 26 Nov 2020 22:15:50 GMT</pubDate>
            <atom:updated>2020-11-28T19:06:27.962Z</atom:updated>
            <content:encoded><![CDATA[<h3>Contract Tests With Pact JVM — The Tricky Parts</h3><p>Contract testing is a great technique that provides a reliable way to verify the agreed boundaries between your microservices without all the complexity of integration testing.</p><p>It has some steep learning curve though. The following post covers some of the technical challenges my team had to overcome when introducing the Pact-based contract testing into our Java microservices world.</p><h3><strong>Which DSL variant shall I use for my Java project?</strong></h3><p><a href="https://github.com/pact-foundation/pact-jvm/tree/master/consumer">Java</a>, <a href="https://github.com/pact-foundation/pact-jvm/tree/master/consumer/java8">Java 8 with lambdas</a>, or <a href="https://github.com/pact-foundation/pact-jvm/tree/master/consumer/groovy">Groovy</a> DSL — which one is the best? That’s the exact question we asked ourselves before jumping into the world of pacts.</p><p>Let’s have a look at an example of JSON structure specified using different JVM DSLs. I’m going to use a product definition you might find in a typical warehouse system, with the following fields:</p><ul><li>productId — a string value using UUID format</li><li>dimensions — a complex object containing decimal values of: width, length, and height</li><li>alternatives — an array of complex objects, each containing a productId and an integer value of count</li></ul><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/4748bf8a1986cba0bedd6f83fead0c1b/href">https://medium.com/media/4748bf8a1986cba0bedd6f83fead0c1b/href</a></iframe><p>Below you can find three code excerpts, limited to body matchers only, using different DSL variants: groovy, java, and java 8 (with lambdas):</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/802feb11d821e8559424c06a6f55c264/href">https://medium.com/media/802feb11d821e8559424c06a6f55c264/href</a></iframe><p>For my team code readability was a key factor when selecting the DSL to define our contracts. Groovy DSL clearly stands out of the crowd here— it’s very concise and reflects the json structure without any additional noise. Some people might complain that it comes with a great learning curve though. However, considering the popularity of the Gradle build tool and Spock test framework, it’s very unlikely that Groovy is going to be something completely new to everyone in your team. Even if it is, it’s going to be a great opportunity to learn and make use of it in other contexts!</p><p>The classic Java DSL is, <a href="https://github.com/pact-foundation/pact-jvm/tree/master/consumer/java8#why-a-new-dsl-implementation">as mentioned by the official Pact documentation</a>, error-prone and hard to read. The need to explicitly open (and close) every element — be it an object or an array — makes it very difficult to follow the levels of the json structure. Another serious drawback is that the DSL doesn’t stop you from making mistakes, as some methods can be used in a specific context only, but are always available. On last word about the style — it’s not very aligned when it comes to method naming — see stringType(...) and uuid(...) matcher methods — which may make it a bit more difficult to understand.</p><p>Even though Java 8 DSL with lambdas seems to be a major improvement over the classic Java DSL, its readability is still far worse compared to Groovy DSL. Having lambdas instead of opening and closing different elements is quite concise, but requires a lot of boilerplate code anyways. Even if you name your lambda parameters using a single letter only, it’s still a lot of arrows and brackets everywhere. There’s also a small, but quite annoying problem to it — the indentation — as IDEs tend to remove the additional whitespace that could indicate the level in json structure, making everything look like it’s at the root level. The good thing is that it comes with the good old static typing — which may be the reason for some people to prefer it over Groovy DSL.</p><h3><strong>Getting groovy on the right path</strong></h3><p>Great, let’s say you’ve just selected <a href="https://docs.pact.io/implementation_guides/jvm/consumer/groovy/">Groovy DSL for Pact JVM</a> as suggested above, and moved to configuration. After the <a href="https://docs.pact.io/implementation_guides/jvm/consumer/groovy/#usage">initial setup of dependencies in your Gradle project</a>, you created a draft SomeConsumerContractTest.groovy class. Then you ran Gradle build, and boom, all you get is the following failure in your console:</p><pre>Execution failed for task &#39;<strong>:compileTestGroovy</strong>&#39;.<br>&gt; Could not resolve all files for configuration &#39;:<strong>detachedConfiguration1</strong>&#39;.<br>   &gt; Could not find <strong>org.codehaus.groovy:groovy:4.1.0</strong>.</pre><p>You might wonder, what is detachedConfiguration1 or why is Gradle looking for some weird version — 4.1.0 — that’s exactly the same as of Pact’s groovy consumer?</p><p>It turns out there’s a naming clash between Gradle groovy plugin and Pact’s groovy consumer that leads to mysterious errors like this. It all boils down to how Gradle groovy plugin <a href="https://docs.gradle.org/current/userguide/groovy_plugin.html#sec:automatic_configuration_of_groovyclasspath">handles automatic configuration of </a><a href="https://docs.gradle.org/current/userguide/groovy_plugin.html#sec:automatic_configuration_of_groovyclasspath">groovyClasspat</a>h — in a nutshell, it looks for an artifact named groovy or groovy-all, without taking the group name into consideration…</p><h4>How to avoid it?</h4><p>There’s a straightforward fix for it — you need to declare the groovyClasspath yourself to avoid the automatic configuration, i.e.:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/fd53ace9f23b1477676f432b2103ea5b/href">https://medium.com/media/fd53ace9f23b1477676f432b2103ea5b/href</a></iframe><h3><strong>Hardcoded vs generated values</strong></h3><p>This one is more about the right approach rather than technical aspects of a selected Pact DSL.</p><p>When defining a consumer-driven contract it’s recommended to focus on the request or response structure and avoid exact values matching.</p><p>So, instead of putting up a contract with hardcoded values of Tom in a request and Hello Tom! in a response:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/2ca443e7e3a06fe46a4452ff987c082a/href">https://medium.com/media/2ca443e7e3a06fe46a4452ff987c082a/href</a></iframe><p>You, as an API consumer, should rather focus on data types:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/a3d6961d43a94f25151544fb89d22c21/href">https://medium.com/media/a3d6961d43a94f25151544fb89d22c21/href</a></iframe><p>However that’s only half the story. Let’s consider a provider perspective now. When verifying your consumer contracts you need to set up external dependencies properly — i.e. stub some responses from services you depend on.</p><p>With a pact written as in <em>Example B </em>you’ll always get some randomly generated String in a name field of a POST request to your /hello endpoint. That requires very liberal, generic mocking on provider side, something like:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/7460209ea8acf9b2be03112e32dd20e4/href">https://medium.com/media/7460209ea8acf9b2be03112e32dd20e4/href</a></iframe><p>Even though it may be a sufficient approach in simple cases, it becomes tedious for a provider, especially when there are multiple consumers of his API that require slightly different responses depending on the name parameter.</p><h4>What’s the recommended approach?</h4><p>Use Pact’s DSL matchers that can take an example as an argument! Define your contract like this:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/1e7ea7013c85cd831d2504f28381e192/href">https://medium.com/media/1e7ea7013c85cd831d2504f28381e192/href</a></iframe><p>Notice the usage of string(&#39;Tom&#39;) in a request, and string(&#39;Hello Tom!&#39;) in a response. They are useful for both sides of a pact — a consumer and provider. Let’s find out how they can make the most out of it.</p><h4>Provider’s perspective</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1022/1*7Pz59_mtbQv3_YazP2ypmw.png" /></figure><p>Provider is going to verify if its responses fulfill the Consumer needs and match against the type string in the response (❶). What’s more, the example string value &#39;Tom&#39; (❷) from the request may be used when mocking external dependencies in a dedicated test class for verifying contracts on provider side, i.e.:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/1d7037451f7d1a3959cc597b362c568d/href">https://medium.com/media/1d7037451f7d1a3959cc597b362c568d/href</a></iframe><h4>Consumer’s perspective</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1022/1*zpn4EKRCO_0d5veZwVP_5A.png" /></figure><p>When creating the consumer-driven contract there’s a promise to the provider that any requests sent to it will match against the type string (❸). This will be verified in a test generating the pact in Consumer’s codebase. Additionally, the string value &#39;Hello Tom!&#39; (❹) may be used when running and verifying the pact and its generated response, i.e.:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/4acfb13e3af7e0fa55c512c14ab97ca4/href">https://medium.com/media/4acfb13e3af7e0fa55c512c14ab97ca4/href</a></iframe><h3><strong>Heterogeneous collections matching</strong></h3><p>At first, let’s consider the following JSON response example:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/b18d1bd7db9ab1ca9b3afafe0120bb30/href">https://medium.com/media/b18d1bd7db9ab1ca9b3afafe0120bb30/href</a></iframe><p>The items array may contain items of two types: a regular item with a price, and a discounted item that has a discounted price only. They both share some common fields: id and type. The array is heterogeneous, meaning its elements’ structure may vary.</p><p>Some people consider it as an example of bad API design. In fact, according to Pact’s philosophy, it is expected that arrays are homogeneous — their elements have always the same structure. Hence the eachLike() and other matchers for you to verify array contents in your contracts.</p><p>As for now with Pact standard ver. 3, there’s no support for array matchers that would work as: <em>match if array element matches any of the specified structures.</em></p><p>Even though it may be viewed as a badly designed API, heterogeneous arrays may appear in your contract tests from time to time. How to handle it with Pact?</p><h4>Mixed approach — specific elements with matchers</h4><p>One approach would be to define a contract as if our array was homogeneous, meaning including all the fields from both types of items together, i.e:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/d3a130f0cf228fbfa369471f7aa12b34/href">https://medium.com/media/d3a130f0cf228fbfa369471f7aa12b34/href</a></iframe><p>The approach above will, however, generate a response containing an item with a structure that’s invalid from both business and structural point of view — we shouldn’t see a regular item with discounted price.</p><p>Whereas in some cases it may be enough to test a typical structure and leave the less common ones to component tests I believe there’s a better approach to it. Consider the following contract definition:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/3079a5ad1d3a859d5a3316c3432e2b88/href">https://medium.com/media/3079a5ad1d3a859d5a3316c3432e2b88/href</a></iframe><p>Please mind there are some trade offs here. Firstly, we sacrifice the <em>“avoid exact value matching”</em> principle in order to make sure we cover all of the expected structures in our contract tests.</p><p>Secondly, having items defined with an exact number of variants puts additional effort on the producer. It wouldn’t be possible to be liberal about the generated response when verifying consumer expectations on producer side anymore, but rather require exactly two items in the array, ordered in a way to match the expected structures — first a regular item and then a discounted one.</p><h3>Wrap up</h3><p>If you’re in a Java team thinking about introducing Pact-based contract tests — just give it a go! Use Groovy DSL, try to provide your type matchers with some examples wherever possible, and most importantly, do not follow all the Pact principles too rigorously.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=6b2fee5d139c" width="1" height="1" alt=""><hr><p><a href="https://medium.com/swlh/contract-tests-with-pact-jvm-the-tricky-parts-6b2fee5d139c">Contract Tests With Pact JVM — The Tricky Parts</a> was originally published in <a href="https://medium.com/swlh">The Startup</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Code Review — dos and don’ts]]></title>
            <link>https://medium.com/swlh/code-review-dos-and-donts-aefeb84cbc3e?source=rss-e63e806fd875------2</link>
            <guid isPermaLink="false">https://medium.com/p/aefeb84cbc3e</guid>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[coding]]></category>
            <category><![CDATA[java]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[code-review]]></category>
            <dc:creator><![CDATA[Tom Muc]]></dc:creator>
            <pubDate>Sat, 21 Nov 2020 17:05:59 GMT</pubDate>
            <atom:updated>2020-11-28T19:06:56.242Z</atom:updated>
            <content:encoded><![CDATA[<h3>Code Review — dos and don’ts</h3><p>Code review has become an essential practice for many programmers. It comes with a variety of great outcomes, just to name a few:</p><ul><li>it’s a way to improve the quality of your codebase,</li><li>it helps introducing the coding standards in your team or company,</li><li>it can easily boost knowledge within your team,</li><li>it allows junior developers to learn from seniors,</li><li>it allows senior developers to make use of a fresh perspective of a junior.</li></ul><p><em>But the question is, what makes a great code reviewer? How to conduct a review to make the best out of it?</em></p><p>Even though code reviews are widely used in almost all IT companies these days, there are some do’s and don’ts I find not so popular. In the following sections I gathered the best and worst practices I’ve seen in my day-to-day work</p><h4>Do: Understand the purpose</h4><p><em>Don’t: review code without the context</em></p><p>Reviewing code without the context, from my experience, tends to result in minor and low level comments.</p><p>The crucial part of the whole process is not only about pointing out a redundant import statement or a misspelled variable name. You want to focus on unreadability, potential bugs, bad architecture and design, lack of error handling, corner cases, and so on.</p><p>So, before you jump into the code, ask yourself a few questions:</p><ul><li>Is it a new feature or a bug fix?</li><li>How important or urgent is it?</li><li>What’s the business context, what are we going to achieve?</li><li>Who is the expert? Who knows the latest agreements and details around this feature?</li></ul><p>Don’t be afraid to talk about the purpose of the change with the colleague that asks for a review. Having all the answers will help you conduct a meaningful, thorough code review.</p><h4>Do: checkout the code</h4><p><em>Don’t: review it in your browser</em></p><p>This one might look a bit controversial. I know there are great tools to perform code reviews using just your web browser, for instance <em>Atlassian’s Fisheye</em>, <em>JetBrains’ Upsource</em>, or simply tools embedded in <em>Gitlab</em> or <em>Github</em>.</p><p>As a programmer I read code a lot. I’d say I read code way more than write it. You simply have to do it in order to decide what’s the best place to put the new feature into, to look for that nasty bug that keeps you awake at night, to check how the business process works, to learn good practices and new technologies, and so on.</p><p>I mostly use my favourite IDE to browse and read code, I’m accustomed to it. I know the navigation patterns, keyboard shortcuts, I have it customized to my preferences. The web-based code review tools feel too limited to me. Here’s what bothers me the most:</p><ul><li><strong>they usually don’t show the whole file, but rather focus on highlighting changes in a line-by-line comparison. <br></strong>If as a reviewer you only focus on changes of a single line, you will likely miss the big picture. Perhaps the file you’re looking at has just become unmanageable — with tangled, spaghetti code and bad structure. You and your team had never realised that before, because it all happened line-by-line, over a couple of reviews, over a couple of months… <br>Or maybe that new piece of code that’s being reviewed has nothing to do with the rest of the file. Before you know you’d end up with many responsibilities mixed together.<br>My advice here is simple— look around the newly introduced changes, see how they fit into the bigger whole. It’s much easier in your IDE.</li><li><strong>you can’t easily navigate through the code and method calls, but need to jump around different files instead<br></strong>Having many different files and classes achieving some business purpose together it becomes quite a challenge to understand how things work only by reading. <br>The web-based code review tools don’t know if you’re a programmer that likes to understand things with a top-down or bottom-up approach. They just show you a list of changed files and you need to figure out the correct order to browse them yourself.<br>What helps me understand how code works is navigating between method calls, seeing how the flow of control moves from one method to another. IDEs are great at it, they usually offer a dozen of different ways to navigate through the code base. Make use of it!</li><li><strong>you can’t run tests in them<br></strong>Running unit tests is another way of understanding how code works. As TDD-practitioners say: an unit test is an<em> executable</em> code documentation that can never go out of sync with the code. <br>When reviewing code in your IDE you can easily execute some tests, or even better, fiddle with one or two to see if your understanding is correct. I also find it useful to try out the code changes I’m about to suggest as a review comment — I want to make sure the tests still pass and my suggested approach works. Good luck doing any of it via the web-based review tool.</li></ul><h4>Do: mention minor things</h4><p><em>Don’t: leave them unnoticed</em></p><p>Follow the famous boy-scout rule to leave your camp in a better condition than you’ve found it. This applies to your codebase too! Whenever you review some code changes take a good look around. There’s usually something that might be improved without much of a fuss — rename a variable, delete an obsolete import statement, or fix up some javadocs.</p><p>Once this approach becomes popular among your team, you’ll notice how your codebase quality improves over time, with less and less warnings during build, problem indicators in your IDE, or flaky tests.</p><h4>Do: suggest changes</h4><p><em>Don’t: tell others what to do</em></p><p>This one is about the style of your comments. I prefer suggesting rather than telling people what to do. I’d comment:</p><blockquote>Consider using StringBuilder instead of String concatenation.</blockquote><p>rather than:</p><blockquote>Use StringBuilder, that’s the best way.</blockquote><p>Might seem as a minor difference, but it leaves the decision up to the author and sounds friendlier.</p><p>What’s more, wherever possible I refrain myself from comments using adjectives like: easier, nicer, better, because they usually come with a personal sense of style, and their interpretation may vary among your colleagues.</p><p>From my experience people, especially programmers, don’t like being told what to do. They may feel under attack and automatically switch to defensive mode, trying to justify their decisions. If you ever find yourself in a fierce code review discussion because of that, don’t hesitate to simply talk to each other. Go to your colleague’s desk (or call him), listen to each other, and try to understand the other perspective. You want to collaborate, not fight with each other.</p><h4>Do: make it a habit</h4><p><em>Don’t: keep others waiting</em></p><p>Achieving goals with your team requires teamwork. That means you should keep everyone as productive as possible and limit the time spent on waiting for each other. That’s why I usually start my working day with a cup of coffee and a bunch of merge requests to review for my colleagues. I refrain myself from jumping straight to my coding tasks, even though writing code is much more exciting than reading it. Instead I rather do as much as possible to unblock my teammates. Believe me this approach pays back! If your team members follow the same approach you’ll get <em>your</em> tasks reviewed (and finished) faster.</p><p>A good starting point is to set aside some time for code reviews <em>every</em> <em>day</em> —try with a 30 minute slot in the morning. Starting with a fresh mind, not occupied by the tasks from your to-do list yet, will help you keep focused and be thorough while reviewing code.</p><h4>Wrap up</h4><p>Keep in mind that reviewing code is a skill that, as any other skill, requires practice and time to master.</p><p>Understand the context, use your IDE, be thorough, be nice and don’t keep others waiting. I hope that following these simple rules will help you become a great reviewer and avoid all the pitfalls I fell into.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=aefeb84cbc3e" width="1" height="1" alt=""><hr><p><a href="https://medium.com/swlh/code-review-dos-and-donts-aefeb84cbc3e">Code Review — dos and don’ts</a> was originally published in <a href="https://medium.com/swlh">The Startup</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>