<?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 Gayan Perera on Medium]]></title>
        <description><![CDATA[Stories by Gayan Perera on Medium]]></description>
        <link>https://medium.com/@gayanper?source=rss-50d22d55ee39------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*wdk3COg-K4kLppIv33-ckg.jpeg</url>
            <title>Stories by Gayan Perera on Medium</title>
            <link>https://medium.com/@gayanper?source=rss-50d22d55ee39------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Wed, 18 Nov 2026 19:03:52 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@gayanper/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[Leadership in a Tech Team]]></title>
            <link>https://medium.com/@gayanper/leadership-in-a-tech-team-f5d6c8bdf1be?source=rss-50d22d55ee39------2</link>
            <guid isPermaLink="false">https://medium.com/p/f5d6c8bdf1be</guid>
            <category><![CDATA[team-culture]]></category>
            <category><![CDATA[leadership]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[engineering]]></category>
            <category><![CDATA[tech-lead]]></category>
            <dc:creator><![CDATA[Gayan Perera]]></dc:creator>
            <pubDate>Tue, 11 Nov 2025 18:44:17 GMT</pubDate>
            <atom:updated>2025-11-11T18:44:17.826Z</atom:updated>
            <content:encoded><![CDATA[<p><em>Reflections on trust, failure, and empowerment in technical leadership.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*GUNsUv5jAOO4iVJb" /><figcaption>Photo by <a href="https://unsplash.com/@jannerboy62?utm_source=medium&amp;utm_medium=referral">Nick Fewings</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><p>Experience has a way of teaching you what no book or advice ever can.</p><p>Over the years, I’ve had the opportunity to work both as a Tech Lead and under several Tech Leads. Each experience has taught me something valuable about what real leadership looks like — and what it doesn’t.</p><p>Leadership isn’t about being the smartest person in the room. It’s about how you make people feel while they build with you.</p><h3>Trust and Ownership</h3><p>A lack of trust often comes from good intentions — the desire to make sure nothing goes wrong. But sometimes, it’s also about fear: fear of being blamed if the team fails.</p><p>When a leader doesn’t trust their team, it quietly turns into a master–slave setup. People stop thinking for themselves. They do what they’re told, not because they agree, but because it’s safer.</p><p>True leadership means creating an environment where people can make decisions and know that you’ll stand with them if things don’t go perfectly. Trust is not about removing accountability — it’s about <em>sharing it.</em></p><h3>The Trap of Perfection</h3><p>Nitpicking every little detail can kill motivation. The question to ask isn’t <em>“Is this perfect?”</em> — it’s <em>“Is this important?”</em></p><p>Often, what we’re optimizing for is our personal preference, not team quality. If everything has to look exactly how <em>you</em> would do it, the team learns one thing very quickly:</p><blockquote><em>“I’ll just wait until the lead tells me how they want it.”</em></blockquote><p>Good leads focus on principles rather than preferences. They raise the bar without raising anxiety.</p><h3>Micromanagement vs. Empowerment</h3><p>Supervising every decision might come from care, but it often looks like control. When a Tech Lead tries to steer every move, the team stops offering ideas.</p><p>Great Tech Leads don’t hand out instructions — they provide <em>context.</em></p><p>They say:</p><blockquote><em>“Here’s the goal, here’s why it matters. What do you think is the best way to get there?”</em></blockquote><p>That shift changes everything. It turns people from executors into collaborators, and it helps them grow confidence in their own judgment.</p><h3>Let the Team Fail (Safely)</h3><p>Sometimes the best way to help your team grow is to let them fail — safely. Even when you know their chosen path might not work, letting them try, reflect, and learn from the experience can be far more valuable than stepping in to stop it.</p><p>There’s a big difference between failing and failing recklessly.</p><p>A good leader creates <em>safe-to-fail</em> experiments — small enough not to cause damage, but big enough to produce real learning.</p><p>When disagreement arises and both sides have valid reasoning, step back and let the team decide. Then, once the outcome is clear, use it as a retrospective moment:</p><blockquote><em>“What did we learn from this? What would we do differently next time?”</em></blockquote><p>That’s how you build a self-correcting team — one that learns and improves without constant supervision.</p><h3>Balancing Direction and Freedom</h3><p>Leadership is about finding the right balance between guiding and letting go. Too little direction, and the team drifts. Too much, and they suffocate.</p><p>The best leaders set clear intent but leave freedom in <em>how</em> things are done. They lead by creating context, not control.</p><p>At the end of the day, leadership isn’t about avoiding mistakes. It’s about helping your team become strong enough to handle them.</p><p><strong>If this resonated with you</strong>, share your experience in the comments:</p><p>What kind of leadership helped <em>you</em> grow the most — the one that protected you from mistakes, or the one that let you fail and learn?</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=f5d6c8bdf1be" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Implementing Entity Audit Log with Prisma]]></title>
            <link>https://medium.com/@gayanper/implementing-entity-audit-log-with-prisma-9cd3c15f6b8e?source=rss-50d22d55ee39------2</link>
            <guid isPermaLink="false">https://medium.com/p/9cd3c15f6b8e</guid>
            <category><![CDATA[design-patterns]]></category>
            <category><![CDATA[audit-logs]]></category>
            <category><![CDATA[typescript]]></category>
            <category><![CDATA[nodejs-development]]></category>
            <category><![CDATA[prisma]]></category>
            <dc:creator><![CDATA[Gayan Perera]]></dc:creator>
            <pubDate>Sat, 16 Aug 2025 14:43:16 GMT</pubDate>
            <atom:updated>2025-08-16T14:43:16.046Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*TTXzqx6QlSBxG4i1" /><figcaption>Photo by <a href="https://unsplash.com/@mediamodifier?utm_source=medium&amp;utm_medium=referral">Mediamodifier</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><h3>What is an Audit Log</h3><p>An audit log is a record of changes made to data within an application. It provides a detailed history of who made changes, what changes were made, and when they occurred. Audit logs are essential for maintaining data integrity, security, and accountability in applications.</p><h3>What is Prisma</h3><p>Prisma is an open-source database toolkit that simplifies database access and management for developers. It provides a type-safe and intuitive API for interacting with databases, allowing developers to focus on building applications without worrying about the underlying database queries. Prisma supports various databases, including PostgreSQL, MySQL, SQLite, and more.</p><p>In this article, we will explore how to implement entity audit logging using Prisma, including the necessary schema definitions, middleware setup, and querying of audit logs. The example use case we will consider is a system which manages employees, departments, and assignments. In this system, we can observe the following business entities:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Oo2C0csphhzlcs_zSvbjJw.png" /></figure><p>Now traditional ORM based Entity Audit Log frameworks often rely on history table per Entity. That means each entity (e.g., Employee, Department, Assignment) would have its own dedicated history table to track changes. This approach can lead to a proliferation of tables and increased complexity in managing audit logs across different entities. Instead, we can implement a more streamlined solution using a single audit log table that captures changes for all entities in a unified manner.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/612/1*ZfdknuiFch1JvuOKoZvmiw.png" /></figure><p>With this structure in place, we can easily track changes across all entities without the need for multiple history tables. Each entry in the EntityHistory table will contain all the necessary information to understand the context of the change, including the entity type, ID, action performed, user who made the change, and timestamps. The diff field will capture the specific changes made to the entity, while the snapshot field will store the complete state of the entity before the change. This unified approach simplifies the management of audit logs and provides a comprehensive view of all changes within the system.</p><p>We could implement this using a separate component which will store the actual generation of diff and snapshot data together with other related metadata. Then this component can be used in all CRUD operations to automatically log changes to the EntityHistory table.</p><p>The main downside of this approach is that it introduces additional complexity in terms of managing the audit log component. Missing to properly configure this component in all relevant parts of the application could lead to gaps in the audit log, making it difficult to track changes accurately.</p><p>So a better approach is to integrate the audit logging functionality directly into the Prisma middleware layer. By doing this, we can ensure that all relevant changes are automatically captured and logged without requiring explicit calls to the audit log component in every CRUD operation. This approach leverages Prisma’s middleware capabilities to intercept database operations and generate the necessary audit log entries on-the-fly. We can configure the middleware to maintain audit logs for all relevant entities only.</p><p>Following is a draft implementation of such middleware:</p><pre>import { Prisma, type PrismaClient } from &quot;@prisma/client&quot;;<br>import { ContextManager } from &quot;../contextMiddleware&quot;;<br>import type { Action, EntityType, Snapshot } from &quot;../models/EntityHistory&quot;;<br>import { diff } from &quot;./EntityDiff&quot;;<br><br>export function createEntityHistoryMiddleware(client: PrismaClient) {<br>  const fetchCurrentSnapshot = async (<br>    id: number | undefined,<br>    model: &quot;Employee&quot; | &quot;Department&quot; | &quot;Assignment&quot; | &quot;EntityHistory&quot;<br>  ): Promise&lt;Snapshot | null&gt; =&gt; {<br>    switch (model) {<br>      case &quot;Employee&quot;:<br>        return client.employee.findUnique({ where: { id } });<br>      case &quot;Department&quot;:<br>        return client.department.findUnique({ where: { id } });<br>      case &quot;Assignment&quot;:<br>        return client.assignment.findUnique({ where: { id } });<br>      default:<br>        return null;<br>    }<br>  };<br><br>  const record = async (<br>    action: Action,<br>    current: Snapshot | null,<br>    incoming: Snapshot | null<br>  ): Promise&lt;void&gt; =&gt; {<br>    if (!incoming &amp;&amp; !current) {<br>      throw new Error(&quot;At least one of current or incoming must be provided&quot;);<br>    }<br>    const snapshot = current ? current : incoming!;<br>    const entityId = snapshot.id;<br><br>    if (!entityId) {<br>      throw new Error(&quot;Snapshot must have an id&quot;);<br>    }<br><br>    const diffs = diff(current, incoming);<br>    if (diffs.patches.length === 0) {<br>      return; // No changes to record<br>    }<br><br>    const context = ContextManager.get();<br>    const currentUser = context?.userId || &quot;system&quot;;<br><br>    await client.entityHistory.create({<br>      data: {<br>        action: action,<br>        changedBy: currentUser,<br>        changedAt: new Date(),<br>        entityId: entityId,<br>        entityType: getEntityType(snapshot),<br>        diff: JSON.stringify(diffs),<br>        snapshot: JSON.stringify(current),<br>      },<br>    });<br>  };<br><br>  const getEntityType = (snapshot: Snapshot): EntityType =&gt; {<br>    if (&quot;firstName&quot; in snapshot) {<br>      return &quot;employee&quot;;<br>    } else if (&quot;managerId&quot; in snapshot) {<br>      return &quot;department&quot;;<br>    } else {<br>      return &quot;assignment&quot;;<br>    }<br>  };<br><br>  return Prisma.defineExtension({<br>    query: {<br>      $allModels: {<br>        async create({ args, query, model }) {<br>          if (model === &quot;EntityHistory&quot;) {<br>            return;<br>          }<br><br>          const incoming = await query(args);<br>          await record(&quot;created&quot;, null, incoming);<br>          return incoming;<br>        },<br><br>        async createMany({ args, query, model }) {<br>          throw new Error(&quot;Not supported by EntityHistoryMiddleware&quot;);<br>        },<br><br>        async update({ args, query, model }) {<br>          if (model === &quot;EntityHistory&quot;) {<br>            return;<br>          }<br><br>          const current = await fetchCurrentSnapshot(args.where.id, model);<br>          const incoming = await query(args);<br>          await record(&quot;changed&quot;, current, incoming);<br>          return incoming;<br>        },<br><br>        async updateMany({ args, query, model }) {<br>          throw new Error(&quot;Not supported by EntityHistoryMiddleware&quot;);<br>        },<br><br>        async delete({ args, query, model }) {<br>          if (model === &quot;EntityHistory&quot;) {<br>            return;<br>          }<br><br>          const current = await fetchCurrentSnapshot(args.where.id, model);<br>          const incoming = await query(args);<br>          await record(&quot;deleted&quot;, current, incoming);<br>          return incoming;<br>        },<br><br>        async deleteMany({ args, query, model }) {<br>          throw new Error(&quot;Not supported by EntityHistoryMiddleware&quot;);<br>        },<br>      },<br>    },<br>  });<br>}</pre><p>The EntityDiff module implements the diffing logic for the entity snapshots. This implementation I have chosen to keep the diff in JSON Patch format, which is a standard format for representing changes to JSON documents. This allows for a more structured representation of the changes made to each entity, making it easier to understand and apply the changes if needed. Also at the same time a consumer can easily interpret the changes and present it visually in a UI component.</p><p>The complete implementation of this solution can be found in the GitHub repository <a href="https://github.com/gayanper/gap-techblog-src/tree/main/entity-audit-trail">https://github.com/gayanper/gap-techblog-src/tree/main/entity-audit-trail</a></p><p>One could clone the repository and go into directory entity-audit-trail to explore the code further. Also you could simply execute the following commands in order to populate a local database with some sample data:</p><pre>docker compose --file docker-compose.yaml up<br><br>npm install<br>npm run build<br>npm run migrate<br>npm run start-server<br>npx run seed-scenarios</pre><p>and explore how it works for yourself.</p><h3>Performance</h3><p>I have not evaluated the performance of this solution in detail, but from the design itself it is obvious that this is not suitable for high write-volume applications. But this should be sufficient for most applications which do not have a very high write volume.</p><p>If a use case expects faster queries for audit logs with filtering support, one could consider separating the JSON fields into a separate table given these fields can be large in size. This could improve performance on queries which do not require the full snapshot or diff data. But this should be done after careful consideration of the specific use case and performance requirements.</p><h3>Wrapping up</h3><p>Entity audit logs bring clarity and trust to your data. By capturing snapshots and JSON-Patch diffs at the Prisma middleware level you get consistent, centralized history without scattering audit logic throughout your codebase. The example in this repo is a practical starting point — tweak the schema, diff strategy, and retention to fit your needs.</p><p>Give it a spin locally, open an issue or PR with ideas, and enjoy cleaner, more auditable systems.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=9cd3c15f6b8e" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Why Skipping Runtime Type Safety Could Be the Costliest Mistake in Your Code?]]></title>
            <link>https://medium.com/@gayanper/why-skipping-runtime-type-safety-could-be-the-costliest-mistake-in-your-code-59084f996d46?source=rss-50d22d55ee39------2</link>
            <guid isPermaLink="false">https://medium.com/p/59084f996d46</guid>
            <category><![CDATA[error-handling]]></category>
            <category><![CDATA[typescript]]></category>
            <category><![CDATA[go]]></category>
            <category><![CDATA[java]]></category>
            <category><![CDATA[programming]]></category>
            <dc:creator><![CDATA[Gayan Perera]]></dc:creator>
            <pubDate>Sat, 19 Oct 2024 18:19:30 GMT</pubDate>
            <atom:updated>2024-10-19T18:19:30.928Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*NCp3FV6kqcBTq4Y9" /><figcaption>Photo by <a href="https://unsplash.com/@ahsanjaya?utm_source=medium&amp;utm_medium=referral">Muhammad Daudy</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><p>Most developers and engineers frequently discuss Language Type Safety when discussing programming language choices. One of the recent I heard was</p><blockquote>Typescript is a Type Safe Language, It will help us to write better code which has less runtime errors due to type issues.</blockquote><p>While most of this statement is true since most of the issues are due to programming errors, having strong type systems and compile type enforcement can help avoid many problems. But it is vital that we also focus on Runtime Type Safety of the chosen Language runtime since most of the code we write nowadays exchanges information with other services through data serialization.</p><p>Before we dive into Runtime Type Safety, let&#39;s look at what Compile Time Type Safety looks like in a Language that has a Static Type System.</p><h3>Compile Time Type Safety</h3><p>A statically typed language always makes sure the variables you define have a type either by defining it explicitly or by deriving it implicitly by the first value you assign to the variable. Once the variable type is known to the compiler, then in the rest of the program it checks all the operations you try to perform on the variable are valid operations for that given type. Otherwise, the compilation of your program fails. Above is a most simplest form of explanation among many other things.</p><p>Let&#39;s look at some examples</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/445/1*9fv983qgRkKAvq2S0q4DWw.png" /><figcaption>Typescript</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/894/1*aE_PuBWN70ajKUPWW85vsg.png" /><figcaption>GoLang</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/527/1*cWmfdKleYXCf-6TP02whug.png" /><figcaption>Java</figcaption></figure><p>So as you can see above all three languages have type-checking which it checks the operations on variables and issues compiler errors.</p><p>Now once these programs are compiled, can we make sure the same safety checks are applied at runtime to keep this behavior?</p><h3>Runtime Time Type Safety</h3><p>Now you might ask if the program was compiled with types-checks, how can something change in the runtime? Let&#39;s look at some possibilities</p><ol><li>When deserializing data either from files or from over the wire transport form, the type of data we try to set into the program could be different</li><li>When using reflection base code, where program variables are updated using reflection, the values that might be set might be different.</li></ol><p>Let&#39;s compare the above languages with some simple examples that focus on deserialization/unmarshalling since it is a mostly used scenario nowadays in programs.</p><h4>Typescript</h4><pre>const json = `{<br>    &quot;name&quot; : &quot;John Wick&quot;,<br>    &quot;cityCode&quot; : &quot;981&quot;<br>}`;<br><br>class Person {<br>    name: string;<br>    cityCode: number;<br><br>    constructor(name: string, cityCode: number) {<br>        this.name = name;<br>        this.cityCode = cityCode;<br>    }<br>};<br><br>class City {<br>    code: number;<br>    name: string;<br><br>    constructor(code: number, name: string) {<br>        this.code = code;<br>        this.name = name;<br>    }<br>}<br><br><br>const cities = new Map&lt;number, City&gt;([[981, new City(981, &#39;NY&#39;)], [675, new City(675, &#39;LA&#39;)]]);<br>const person = JSON.parse(json) as Person;<br><br>console.log(`Name: ${person.name}`);<br>console.log(`City Code: ${person.cityCode}`);<br>console.log(`City Name: ${cities.get(person.cityCode)?.name || &#39;Missing&#39;}`);</pre><p>The output</p><pre>Name: John Wick<br>City Code: 981<br>City Name: Missing</pre><p>As you can see in the above code, we expect the cityCode to be a number, But the JSON payload has it as a string , The program fails to raise a type mismatch error and at the same time since types don’t match at runtime, it fails to resolve the City object from the cityCode .</p><p>Interestingly debugging and inspecting the code will show that, the runtime value is a string even though the class member is defined as a number.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/814/1*rNkrp8yZf09_JFLQxdaljA.png" /><figcaption>Debug Console</figcaption></figure><h4>GoLang</h4><p>The Go version of the above Typescript code</p><pre>package main<br><br>import (<br> &quot;encoding/json&quot;<br> &quot;fmt&quot;<br> &quot;log&quot;<br>)<br><br>func main()  {<br> jsonStr := `{<br>  &quot;name&quot; : &quot;John Wick&quot;,<br>  &quot;cityCode&quot; : &quot;981&quot;<br> }`<br><br> type City struct {<br>  Code  int<br>  Name string<br> }<br><br> type Person struct {<br>   Name string `json:&quot;name&quot;`<br>   CityCode int `json:&quot;cityCode&quot;`<br> }<br><br> cities := map[int]City{<br>  981: {981, &quot;NY&quot;},<br>  675: {675, &quot;LA&quot;},<br> }<br><br> var person Person<br> err := json.Unmarshal([]byte(jsonStr), &amp;person)<br> if err != nil {<br>  log.Fatalf(&quot;error parsing json: %v&quot;, err)<br> }<br> fmt.Println(&quot;Name:&quot;, person.Name)<br> fmt.Println(&quot;City Code:&quot;, person.CityCode)<br> if city := cities[person.CityCode]; city != (City{}) {<br>  fmt.Println(&quot;City Name:&quot;, city.Name)<br> }<br>}</pre><p>Output</p><pre>2024/10/19 18:49:42 error parsing json: json: cannot unmarshal string into <br>Go struct field Person.cityCode of type int exit status 1</pre><p>As you can see the Go runtime performs type-checking while unmarshalling the JSON payload. This will be the same if reflection is used.</p><h4>Java</h4><p>The Java version of the above Typescript code, but instead of using JSON, Java’s native object unmarshalling (a.k.a Deserialization) is used since Java JSON support needs external library support.</p><p>The following first code is used to perform the serialization where the cityCode is string . The second code is used to perform the deserialization where the cityCode is expected as anint .</p><p><strong>Note:</strong> Even though the code blocks are defined as two separate blocks when executing both blocks were executed by commenting other inside the same source file to make sure the serialization/deserialization class information is kept the same.</p><pre>import static java.io.IO.println;<br><br>import java.io.FileNotFoundException;<br>import java.io.FileOutputStream;<br>import java.io.IOException;<br>import java.io.ObjectOutputStream;<br>import java.io.Serializable;<br><br>void main() throws FileNotFoundException, IOException, ClassNotFoundException {<br>    writeObj();<br>}<br><br>void writeObj() throws FileNotFoundException, IOException {<br>    var person = new Person(&quot;JonhWick&quot;, &quot;981&quot;);<br>    <br>    try (var fileOut = new FileOutputStream(&quot;./person.ser&quot;); var out = new ObjectOutputStream(fileOut)) {<br>        out.writeObject(person);<br>    }<br>}<br><br>record Person(String name, String cityCode) implements Serializable {<br>}</pre><pre>import static java.io.IO.println;<br><br>import java.io.FileInputStream;<br>import java.io.FileNotFoundException;<br>import java.io.IOException;<br>import java.io.ObjectInputStream;<br>import java.io.Serializable;<br>import java.util.Map;<br>import java.util.Optional;<br><br>void main() throws FileNotFoundException, IOException, ClassNotFoundException {<br>    readObj();<br>}<br><br>void readObj() throws FileNotFoundException, IOException, ClassNotFoundException {<br>    var cities = Map.of(981, new City(981, &quot;NY&quot;), 675, new City(675, &quot;LA&quot;));<br>    <br>    try (var fileIn = new FileInputStream(&quot;./person.ser&quot;); var objIn = new ObjectInputStream(fileIn)) {<br>        Person person = (Person) objIn.readObject();<br>        println(String.format(&quot;Name: %s&quot;, person.name()));<br>        println(String.format(&quot;City Code: %s&quot;, person.cityCode()));<br>        println(String.format(&quot;City Name: %s&quot;,<br>                Optional.ofNullable(cities.get(person.cityCode())).map(City::name).orElse(&quot;Missing&quot;)));<br>    }<br>}<br><br>record City(int code, String name) {<br>}<br><br>record Person(String name, int cityCode) implements Serializable {<br>}</pre><p>Output</p><pre>Exception in thread &quot;main&quot; java.io.InvalidClassException: app$Person; incompatible types for field cityCode<br>        at java.base/java.io.ObjectStreamClass.matchFields(ObjectStreamClass.java:2219)<br>        at java.base/java.io.ObjectStreamClass.getReflector(ObjectStreamClass.java:2140)<br>        at java.base/java.io.ObjectStreamClass.initNonProxy(ObjectStreamClass.java:664)<br>        at java.base/java.io.ObjectInputStream.readNonProxyDesc(ObjectInputStream.java:2072)<br>        at java.base/java.io.ObjectInputStream.readClassDesc(ObjectInputStream.java:1915)<br>        at java.base/java.io.ObjectInputStream.readOrdinaryObject(ObjectInputStream.java:2246)<br>        at java.base/java.io.ObjectInputStream.readObject0(ObjectInputStream.java:1750)<br>        at java.base/java.io.ObjectInputStream.readObject(ObjectInputStream.java:528)<br>        at java.base/java.io.ObjectInputStream.readObject(ObjectInputStream.java:486)<br>        at app.readObj(app.java:22)<br>        at app.main(app.java:15)</pre><p>As you can see the Java runtime performs type-checking while deserializing payload. This will be the same if reflection is used.</p><p>Now even though we see that Typescript doesn’t do the same kind of type-checking at runtime as Go and Java do, this doesn’t mean Typescript is an unsafe language.</p><p>So selecting which language to use depends on your usecase, if what we observed with Typescript could be a critical business failure, then it is something you should strongly evaluate again and reconsider.</p><p>By now you have a clear idea about</p><ul><li>What is Compile Time Type-Safety</li><li>What is Runtime Type-Safety</li></ul><p>So the next time when you choose a programming language this might help you to make a better decision.</p><p>Happy Coding. 👨‍💻</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=59084f996d46" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[ Boost Your AWS Lambda Inner Dev Loop Efficiency!]]></title>
            <link>https://medium.com/@gayanper/boost-your-aws-lambda-inner-dev-loop-efficiency-be639d3cd3e4?source=rss-50d22d55ee39------2</link>
            <guid isPermaLink="false">https://medium.com/p/be639d3cd3e4</guid>
            <category><![CDATA[aws-lambda]]></category>
            <category><![CDATA[tools]]></category>
            <category><![CDATA[developer-productivity]]></category>
            <dc:creator><![CDATA[Gayan Perera]]></dc:creator>
            <pubDate>Sat, 28 Sep 2024 17:28:12 GMT</pubDate>
            <atom:updated>2024-09-28T17:28:12.413Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*nlbIF7oiL3c_eC_P" /><figcaption>Photo by <a href="https://unsplash.com/@glenncarstenspeters?utm_source=medium&amp;utm_medium=referral">Glenn Carstens-Peters</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><p>In this story, I look at how different AWS Tools can be used to make the developer more efficient in developing AWS Lambda functions.</p><h3>What does Developer Efficient mean?</h3><p>How fast we can develop something using a technology stack is one aspect of the efficiency, Another aspect most of the time undermined is the <strong>DevLoop or Inner Dev Loop. </strong>This is similar to CI, but only inside the developer’s workstation while they work on the code. This includes writing code, building, executing, debugging, testing, and repeating all those steps until the task is done.</p><h3>Inner Dev Loop with AWS Lambda</h3><p>I’m used to working with Inner Dev Loop, in my previous company we used Azure Resource with AKS, this allowed me to run the services locally since they are built for AKS, which is Azure Kubernetes, so basically I run a local Kubernetes cluster with all Azure Resource Emulators for debugging and testing. For some services I could just run the service from my IDE and debug it, the services were very simple in design and decoupled from cloud resources so that they can be executed when needed without actual cloud resources.</p><p>I recently started working for a company where I have to work with AWS Lambda. Now I had to find how to get my <strong>Inner Dev Loop </strong>with AWS as well. As with Azure Functions, AWS Lambda also needs the function runtime to execute them, So you can’t easily run the code from your IDE.</p><p>Now with AWS, there are several ways you can achieve this</p><h4>Using SAM CLI</h4><p>Using SAM (<a href="https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/what-is-sam.html">https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/what-is-sam.html</a>) command line interface you can execute your Lambda function locally. But to do that you need to define your SAM Template for it. It’s a bit like writing the Azure Resource Manager Templates even though it&#39;s not the same.</p><h4>Using CDK and SAM CLI</h4><p>You can also use CDK (<a href="https://docs.aws.amazon.com/cdk/v2/guide/home.html">https://docs.aws.amazon.com/cdk/v2/guide/home.htm) </a>to define your AWS Lambda Infrastructure using SourceCode. Now once you do that, you can use this to deploy your application to the cloud as well as you can use the same to run your Lambda Locally using the SAM CLI.</p><p>Since I prefer to always define my cloud infrastructure as code (IaC), using CDK with SAM was a good option for my Inner Dev Loop. Let&#39;s take a simple AWS Lambda function and how to get it done.</p><h3>Inner Dev Loop Setup</h3><p>In this guide, I’m using a VSCode as my IDE/Editor. I’m using Java to build my Lambda Function and using TypeScript for CDK. So let&#39;s look at the Lambda Function Code. Following are the important files, But you can use the SAM CLI to bootstrap a new AWS Lambda Function for you.</p><p>gradle.build</p><pre>plugins {<br>    id &#39;java&#39;<br>}<br><br>repositories {<br>    mavenCentral()<br>}<br><br>dependencies {<br>    implementation &#39;com.amazonaws:aws-lambda-java-core:1.2.2&#39;<br>    implementation &#39;com.amazonaws:aws-lambda-java-events:3.11.0&#39;<br>    testImplementation &#39;junit:junit:4.13.2&#39;<br>}<br><br>sourceCompatibility = 21<br>targetCompatibility = 21<br><br>task packageJar(type: Zip) {<br>    into(&#39;lib&#39;) {<br>        from(jar)<br>        from(configurations.runtimeClasspath)<br>    }<br>}<br>build.dependsOn packageJargr</pre><p>The changes in the gradle.build above is important to create the zip distribution that we will use in the CDK.</p><p>Hello.java</p><pre>package helloworld;<br><br>import java.io.BufferedReader;<br>import java.io.IOException;<br>import java.io.InputStreamReader;<br>import java.net.URL;<br>import java.util.HashMap;<br>import java.util.Map;<br>import java.util.stream.Collectors;<br><br>import com.amazonaws.services.lambda.runtime.Context;<br>import com.amazonaws.services.lambda.runtime.RequestHandler;<br>import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyRequestEvent;<br>import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyResponseEvent;<br><br>/**<br> * Handler for requests to Lambda function.<br> */<br>public class Hello implements RequestHandler&lt;APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent&gt; {<br>    <br>    public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {<br>        Map&lt;String, String&gt; headers = new HashMap&lt;&gt;();<br>        headers.put(&quot;Content-Type&quot;, &quot;application/json&quot;);<br>        headers.put(&quot;X-Custom-Header&quot;, &quot;application/json&quot;);<br>        <br>        APIGatewayProxyResponseEvent response = new APIGatewayProxyResponseEvent().withHeaders(headers);<br>        try {<br>            final String pageContents = this.getPageContents(&quot;https://checkip.amazonaws.com&quot;);<br>            String output = String.format(&quot;{ \&quot;message\&quot;: \&quot;hello world\&quot;, \&quot;location\&quot;: \&quot;%s\&quot; }&quot;, pageContents);<br>            return response.withStatusCode(200).withBody(output);<br>        } catch (IOException e) {<br>            return response.withBody(&quot;{}&quot;).withStatusCode(500);<br>        }<br>    }<br>    <br>    private String getPageContents(String address) throws IOException {<br>        URL url = new URL(address);<br>        try (BufferedReader br = new BufferedReader(new InputStreamReader(url.openStream()))) {<br>            return br.lines().collect(Collectors.joining(System.lineSeparator()));<br>        }<br>    }<br>}</pre><p>Let&#39;s look at the cdk important bits</p><p>package.json</p><pre>{<br>    &quot;name&quot;: &quot;hello-stack&quot;,<br>    &quot;version&quot;: &quot;1.0.0&quot;,<br>    &quot;devDependencies&quot;: {<br>        &quot;@types/node&quot;: &quot;10.17.27&quot;,<br>        &quot;aws-cdk&quot;: &quot;2.160.0&quot;,<br>        &quot;ts-node&quot;: &quot;^9.0.0&quot;,<br>        &quot;typescript&quot;: &quot;~3.9.7&quot;<br>    },<br>    &quot;dependencies&quot;: {<br>        &quot;aws-cdk-lib&quot;: &quot;2.160.0&quot;,<br>        &quot;constructs&quot;: &quot;^10.0.0&quot;,<br>        &quot;source-map-support&quot;: &quot;^0.5.16&quot;<br>    }<br>}</pre><p>tsconfig.json</p><pre>{<br>  &quot;compilerOptions&quot;: {<br>    &quot;target&quot;: &quot;ES2020&quot;,<br>    &quot;module&quot;: &quot;CommonJS&quot;,<br>    &quot;lib&quot;: [&quot;ES2020&quot;],<br>    &quot;strict&quot;: true,<br>    &quot;esModuleInterop&quot;: true,<br>    &quot;skipLibCheck&quot;: true,<br>    &quot;forceConsistentCasingInFileNames&quot;: true,<br>    &quot;moduleResolution&quot;: &quot;node&quot;,<br>    &quot;resolveJsonModule&quot;: true,<br>    &quot;outDir&quot;: &quot;dist&quot;<br>  },<br>  &quot;include&quot;: [&quot;lib/**/*.ts&quot;, &quot;bin/**/*.ts&quot;]<br>}</pre><p>cdk.json</p><pre>{<br>  &quot;app&quot;: &quot;npx ts-node --prefer-ts-exts bin/cdk-app.ts&quot;,<br>  &quot;context&quot;: {}<br>}</pre><p>./lib/hell0-stack.ts</p><p>This defines your stack, stack contains all infrastructure resource needs for your Lambda function and treats it as a single unit. Think of it as a Database transaction, even though it&#39;s not the same.</p><pre>import * as cdk from &#39;aws-cdk-lib&#39;;<br>import { Construct } from &#39;constructs&#39;;<br><br>export class HelloStack extends cdk.Stack {<br>  constructor(scope: Construct, id: string, props?: cdk.StackProps) {<br>    super(scope, id, props);<br>    <br>    const helloLambdaFunction = new cdk.aws_lambda.Function(this, &#39;HelloLambda&#39;, {<br>      runtime: cdk.aws_lambda.Runtime.JAVA_21,<br>      handler: &#39;helloworld.Hello::handleRequest&#39;,<br>      code: cdk.aws_lambda.Code.fromAsset(&#39;../HelloWorldFunction/build/distributions/HelloWorldFunction.zip&#39;),<br>      architecture: cdk.aws_lambda.Architecture.X86_64,<br>      memorySize: 512,<br>      logRetention: cdk.aws_logs.RetentionDays.ONE_WEEK,<br>      tracing: cdk.aws_lambda.Tracing.ACTIVE,<br>      insightsVersion: cdk.aws_lambda.LambdaInsightsVersion.VERSION_1_0_98_0,<br>    });<br><br><br>    const apiGatewayRestApi = new cdk.aws_apigateway.RestApi(this, &#39;HelloApi&#39;, {<br>      restApiName: &#39;Hello API&#39;,<br>      description: &#39;An example API for a hello lambda function&#39;,<br>    });<br><br>    const helloIntegration = new cdk.aws_apigateway.LambdaIntegration(helloLambdaFunction);<br>    apiGatewayRestApi.root.resourceForPath(&#39;/hello&#39;).addMethod(&#39;GET&#39;, helloIntegration);<br>  }<br>}</pre><p>./bin/cdk-app.ts</p><p>This is the cdk entry point for you CDK Lambda stack you just defined and want to deploy.</p><pre>#!/usr/bin/env node<br>import * as cdk from &#39;aws-cdk-lib&#39;;<br>import { HelloStack } from &#39;../lib/hello-stack&#39;;<br><br>const app = new cdk.App();<br>new HelloStack(app, &#39;hello-api-stack&#39;);</pre><p>Now for convenience you can create the following make file to run different sam and cdk commands</p><p>Makefile</p><pre>build:<br> cd ./HelloWorldFunction; ./gradlew build;<br><br>run-local: build<br> cd ./cdk; cdk synth; sam local start-api -t ./cdk.out/hello-api-stack.template.json --region eu-north-1<br><br>debug-local: build<br> cd ./cdk; cdk synth; sam local start-api -t ./cdk.out/hello-api-stack.template.json --region eu-north-1 -d 5858<br><br>deploy: build<br> cd ./cdk; cdk deploy;<br><br>undeploy:<br> cd ./cdk; cdk destroy;</pre><h4>Loop</h4><p>Now as a developer when I change my code, I just run make run-local . This will spin up the lambda function locally and provide a URL to invoke it as following</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/707/1*-h3hOLOIRJq49jeQJFpj6A.png" /></figure><p>Now to debug the lambda function you can use make debug-local which will run the Lambda function in debug mode. Now since I have defined my Lambda function trigger to be an REST API, You first have to trigger the endpoint provided in the console before starting debugging. So let&#39;s see the steps in detail.</p><p>VSCode Lauch Configuratio</p><pre>{<br>    &quot;version&quot;: &quot;0.2.0&quot;,<br>    &quot;configurations&quot;: [<br>        {<br>            &quot;type&quot;: &quot;java&quot;,<br>            &quot;name&quot;: &quot;Lambda&quot;,<br>            &quot;request&quot;: &quot;attach&quot;,<br>            &quot;hostName&quot;: &quot;127.0.0.1&quot;,<br>            &quot;port&quot;: &quot;5858&quot;<br>        }<br>    ]<br>}</pre><p>The port should be what you choose in the command</p><p>sam local start-api -t ./cdk.out/hello-api-stack.template.json — region eu-north-1 -d 5858</p><p><strong>Steps</strong></p><ul><li>First run make debug-local — This will start the SAM Local Stack which will provide you with an API Gateway with the defined REST API endpoint.</li><li>Now trigger the endpoint using the browser or curl. This will start the Lambda Function in debug mode, you should see that the Lambda Function is waiting for the Java debugger to be attached.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/735/1*RC2wOfgXSGA-CEWGMnZ58w.png" /></figure><ul><li>Now as you can see the execution of the Lambda function waits until you connect your Debugger, pretty much similar to how a Java program waits with start with debug agent in <strong><em>server wait</em></strong> mode. Now connect your debugger by running the Attach Launcher config in VSCode.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/998/1*pSk5CjsQZu2n6KlOIf8Pdw.png" /></figure><p>Now you can debug the Lambda function as you normally debug a Java application.</p><p>If you want to just run your Lambda Function without the API Gateway in a situation where you don’t use an API base trigger, then you can just change the following</p><p>sam local start-api -t ./cdk.out/hello-api-stack.template.json — region eu-north-1 -d 5858</p><p>to</p><p>sam local invoke -t ./cdk.out/hello-api-stack.template.json — region eu-north-1 -d 5858 HelloLambda</p><p>in the <strong>Makefile</strong></p><p>I hope these instructions will be useful for you when working with AWS Lambda functions.</p><p>The source code can be found at</p><p><a href="https://github.com/gayanper/gap-techblog-src/tree/main/aws-inner-dev-loop">gap-techblog-src/aws-inner-dev-loop at main · gayanper/gap-techblog-src</a></p><p>Happy Coding in AWS 👨‍💻</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=be639d3cd3e4" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[ Journey to API Design First: Step 1 Specification First]]></title>
            <link>https://medium.com/@gayanper/journey-to-api-design-first-step-1-specification-first-d3ea3d4ff530?source=rss-50d22d55ee39------2</link>
            <guid isPermaLink="false">https://medium.com/p/d3ea3d4ff530</guid>
            <category><![CDATA[api-management]]></category>
            <category><![CDATA[api-design]]></category>
            <category><![CDATA[api]]></category>
            <category><![CDATA[api-development]]></category>
            <category><![CDATA[api-first-approach]]></category>
            <dc:creator><![CDATA[Gayan Perera]]></dc:creator>
            <pubDate>Sun, 25 Aug 2024 10:04:02 GMT</pubDate>
            <atom:updated>2024-08-25T10:04:02.409Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*_Hs_PK-wv1nx3kQ0" /><figcaption>Photo by <a href="https://unsplash.com/@chrislawton?utm_source=medium&amp;utm_medium=referral">Chris Lawton</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><p>There is a lot of buzz in the industry about API First and API Desing First. But most of the time these two terms need to be understood by developers. First, let&#39;s look at the definitions</p><blockquote>The “design first” and “code first” approach are very often opposed to each other.</blockquote><blockquote>The “code first” approach consists in coding the implementation and generating from it a formal description afterwards, usually an OpenAPI Specification file. If you’ve read this blog you know what I think about generating OpenAPI from code in such a case (if not, you should read <a href="https://apihandyman.io/6-reasons-why-generating-openapi-from-code-when-designing-and-documenting-apis-sucks/">6 reasons why generating OpenAPI from code when designing and documenting APIs sucks</a>). This approach has some serious drawbacks but I work with teams who are happy with it. Either you like it or not, either it can have some drawbacks (but also some advantages), should this approach be opposed to “design first”?</blockquote><blockquote>Nope, that’s a wrong debate. The “design first” approach is unfortunately more often than not used to describe something else. Indeed, it is often used to describe the “spec first” approach, an approach in which you describe formally an API using an API specification format such as the OpenAPI Specification before writing any line of code of the implementation.</blockquote><blockquote>So, what means “design first”? The “design first” approach simply means you actually “design” your API before doing anything else. And that could actually be done in both “spec first” and “code first” approaches. Indeed, if I know my API needs a GET /this, and even if <a href="https://apihandyman.io/what-should-come-first-when-designing-an-api/(/6-reasons-why-generating-openapi-from-code-when-designing-and-documenting-apis-sucks/)">generating OpenAPI Spec from code sucks</a>, there’s no big difference between writing OpenAPI Spec code and your favorite language code.</blockquote><blockquote>There’s no big difference … as long as you actually <em>design</em> your API first.</blockquote><p>(<a href="https://apihandyman.io/what-should-come-first-when-designing-an-api/#definitions">https://apihandyman.io/what-should-come-first-when-designing-an-api/#definitions</a>)</p><p>In this story, we will look into the <strong>Spec first</strong> approach where you will start to write the API Specification before writing the code. Now I will not go into details about the benefits of it since reading the above article from APIHandyman will give you enough information to understand the costs and benefits of it.</p><p>But when you start this this journey with this step, most discussions happen about how we can make sure the implementation matches the specification which now the consumers are relying on with their development.</p><p>There are two types of tests that you should look into when making sure the implementation matches the specification.</p><ol><li>Making sure the implementation aligns structurally with the specification. This means in the implementation use the same schemas and endpoints are defined in the specification.</li><li>Making sure the implementation aligns behaviorally with the specification. This means the implementation when executed against real or real-like business data, the consumer can expect the behavior as it is defined in the specification.</li></ol><p>Now in this <strong>step-1 </strong>of the journey, we will see how we can satisfy the Structural integrity of the specification and implementation.</p><p>For this to work we need to make sure our implementation can produce an OpenApi Specification from the code so that we can match that against our specification. Let&#39;s look at how we can do this in a springboot application.</p><p>The following code is based on an example prescription management system which I will use in my future stories as well. But today we use one of its services, <strong>drug-catalog </strong>to show how we can implement a simple structural integrity validation which happens at the build time.</p><h3>Specification</h3><pre>openapi: &quot;3.0.3&quot;<br>info:<br>  title: Drug Catalog API<br>  description: Provide information about medical drugs (a.k.a medicines)<br>  contact:<br>    name: Catalog Team<br>  version: &quot;1.0.0&quot;<br>servers:<br>  - url: http://localhost:8080<br><br>tags:<br>  - name: search<br><br>paths:<br>  /drugs/search:<br>    post:<br>      description: Search drug catalog for drugs by ATC code or generic name of the drug.<br>      tags:<br>        - search<br>      operationId: search<br>      requestBody:<br>        required: true<br>        content:<br>          application/json:<br>            schema:<br>              $ref: &quot;#/components/schemas/DrugSearch&quot;<br>      responses:<br>        &quot;200&quot;:<br>          description: Successful response<br>          content:<br>            application/json:<br>              schema:<br>                $ref: &quot;#/components/schemas/DrugList&quot;<br>        &quot;400&quot;:<br>          description: Business validation error<br>          content:<br>            application/json:<br>              schema:<br>                $ref: &quot;#/components/schemas/ProblemDetail&quot;<br>        &quot;500&quot;:<br>          description: Unhandled server error<br>          content:<br>            application/json:<br>              schema:<br>                $ref: &quot;#/components/schemas/ProblemDetail&quot;<br><br>components:<br>  schemas:<br>    DrugList:<br>      description: Drug list response<br>      type: object<br>      required:<br>        - drugs<br>      properties:<br>        drugs:<br>          type: array<br>          items:<br>            $ref: &quot;#/components/schemas/Drug&quot;<br><br>    DrugSearch:<br>      description: |<br>        The search request for searching drugs in drug catalog.<br>      type: object<br>      required:<br>        - genericName<br>      properties:<br>        genericName:<br>          type: string<br><br>    Manufacturer:<br>      description: Manufacture&#39;s information such as name and contact information.<br>      type: object<br>      properties:<br>        name:<br>          type: string<br>        contactInfo:<br>          type: string<br><br>    Dosage:<br>      description: Information single dosage such as it&#39;s form and strength<br>      type: object<br>      properties:<br>        form:<br>          type: string<br>          enum:<br>            - Tablet<br>            - Capsule<br>            - Infusion<br>            - Liquid<br>        strength:<br>          type: string<br><br>    Names:<br>      description: Names of the drug including the generic name of the drug and the name it is branded as.<br>      type: object<br>      properties:<br>        genericName:<br>          type: string<br>        brandName:<br>          type: string<br>    <br>    Drug:<br>      description: Information about a single drug in the catalog.<br>      type: object<br>      properties:<br>        id:<br>          type: string<br>        names:<br>          $ref: &quot;#/components/schemas/Names&quot;<br>        manufacturer:<br>          $ref: &quot;#/components/schemas/Manufacturer&quot;<br>        dosage:<br>          $ref: &quot;#/components/schemas/Dosage&quot;<br><br>    ProblemDetail:<br>      description: error response as defined in https://datatracker.ietf.org/doc/html/rfc9457<br>      type: object<br>      properties:<br>        type:<br>          type: string<br>          format: uri<br>        title:<br>          type: string<br>        status:<br>          type: integer<br>          format: int32<br>        detail:<br>          type: string<br>        instance:<br>          type: string<br>          format: uri<br>        properties:<br>          type: object<br>          additionalProperties:<br>            type: object</pre><p><strong>Implementation</strong></p><pre>package org.gap.medium.techblogs.drugcatalog.adapters.rest;<br><br>import java.util.List;<br><br>import org.gap.medium.techblogs.drugcatalog.adapters.rest.schemas.DrugList;<br>import org.gap.medium.techblogs.drugcatalog.adapters.rest.schemas.DrugSearch;<br>import org.gap.medium.techblogs.drugcatalog.domain.model.errors.BusinessValidationException;<br>import org.springframework.web.bind.annotation.PostMapping;<br>import org.springframework.web.bind.annotation.RequestBody;<br>import org.springframework.web.bind.annotation.RequestMapping;<br>import org.springframework.web.bind.annotation.RestController;<br><br>import jakarta.validation.constraints.NotNull;<br><br>@RestController<br>@RequestMapping(path = &quot;/drugs&quot;)<br>public class DrugsController {<br>    <br>    @PostMapping(path = &quot;search&quot;, consumes = &quot;application/json&quot;, produces = &quot;application/json&quot;)<br>    public @NotNull DrugList search(@RequestBody @NotNull DrugSearch request)<br>            throws BusinessValidationException, RuntimeException {<br>        return new DrugList(List.of());<br>    }<br>}</pre><pre>package org.gap.medium.techblogs.drugcatalog.adapters.rest;<br><br>import org.gap.medium.techblogs.drugcatalog.domain.model.errors.BusinessValidationException;<br>import org.springframework.http.HttpStatus;<br>import org.springframework.http.MediaType;<br>import org.springframework.http.ProblemDetail;<br>import org.springframework.web.bind.annotation.ExceptionHandler;<br>import org.springframework.web.bind.annotation.RequestMapping;<br>import org.springframework.web.bind.annotation.ResponseStatus;<br>import org.springframework.web.bind.annotation.RestControllerAdvice;<br><br>@RestControllerAdvice<br>public class ErrorHandler {<br>    @ExceptionHandler(BusinessValidationException.class)<br>    @ResponseStatus(value = HttpStatus.BAD_REQUEST)<br>    @RequestMapping(produces = MediaType.APPLICATION_JSON_VALUE)<br>    public ProblemDetail handleBusinessValidationErrors(BusinessValidationException ex) {<br>        var problem = ProblemDetail.forStatus(HttpStatus.BAD_REQUEST);<br>        problem.setDetail(ex.getMessage());<br>        return problem;<br>    }<br>    <br>    @ExceptionHandler(RuntimeException.class)<br>    @ResponseStatus(value = HttpStatus.INTERNAL_SERVER_ERROR)<br>    @RequestMapping(produces = MediaType.APPLICATION_JSON_VALUE)<br>    public ProblemDetail handleRuntimeErrors(RuntimeException ex) {<br>        var problem = ProblemDetail.forStatus(HttpStatus.INTERNAL_SERVER_ERROR);<br>        problem.setDetail(ex.getMessage());<br>        return problem;<br>    }<br>}</pre><pre>package org.gap.medium.techblogs.drugcatalog.adapters.rest.schemas;<br><br>import com.fasterxml.jackson.annotation.JsonProperty;<br><br>public record Drug(String id, Names names, Manufacturer manufacturer, Dosage dosage) {<br>    <br>    public record Names(String genericName, String brandName) {<br>    }<br>    <br>    public record Manufacturer(String name, String contactInfo) {<br>    }<br>    <br>    public record Dosage(DosageForm form, String strength) {<br>    }<br>    <br>    public enum DosageForm {<br>        @JsonProperty(&quot;Tablet&quot;)<br>        TABLET, @JsonProperty(&quot;Capsule&quot;)<br>        CAPSULE, @JsonProperty(&quot;Infusion&quot;)<br>        INFUSION, @JsonProperty(&quot;Liquid&quot;)<br>        LIQUID;<br>    }<br>}</pre><pre>package org.gap.medium.techblogs.drugcatalog.adapters.rest.schemas;<br><br>import java.util.List;<br><br>import jakarta.validation.constraints.NotNull;<br><br>public record DrugList(@NotNull List&lt;Drug&gt; drugs) {<br>    <br>}</pre><pre>package org.gap.medium.techblogs.drugcatalog.adapters.rest.schemas;<br><br>import jakarta.validation.constraints.NotNull;<br><br>public record DrugSearch(@NotNull String genericName) {<br>    <br>}</pre><p><em>The source code link will be shared at the end of this story so that you can download and run it yourself.</em></p><p>Now we can use an OpenApi Specification comparison tool like OASDiff (<a href="https://github.com/Tufin/oasdiff">https://github.com/Tufin/oasdiff</a>) which compares the given two specifications and output report in case there are differences.</p><p>Now if you try to run the tool against the springboot application generated specification and the original specification you will see a lot of differences. Most of the time they are due to additional things in the specification such as</p><ul><li>Tags</li><li>Descriptions</li><li>Summaries</li><li>etc</li></ul><p>which you will not have in the source code. You could try to use OAS annotation to add them to the code. However, the time you will be spending adding them to the source code will not provide any value to you. Since you will use your original specification as your documentation of the API as well.</p><p>So we can exclude the above list of elements from both APIs and then try to compare them will be a much simpler solution to just do a litmus test of your API before finishing the build. This will provide quick feedback to the developer before more expensive tests are executed to find the same issues.</p><p>I wrote a simple shell script to do the above</p><pre>#!/bin/sh<br><br>function remove_elements() {<br>    # make sure the delete the file if exist on disk<br>    if [ -f $2 ]; then<br>        rm -f $2<br>    fi<br><br>    cat $1 \<br>        | yq eval &#39;del(.. | select(has(&quot;tags&quot;)).tags[])&#39; \<br>        | yq eval &#39;del(.. | select(has(&quot;examples&quot;)).examples[])&#39; \<br>        | yq eval &#39;del(.. | select(has(&quot;extensions&quot;)).extensions[])&#39; \<br>        | yq eval &#39;del(.. | select(has(&quot;description&quot;)).description)&#39; \<br>        | yq eval &#39;del(.. | select(has(&quot;title&quot;)).title)&#39; \<br>        | yq eval &#39;del(.. | select(has(&quot;summary&quot;)).summary)&#39; \<br>        | yq eval &#39;del(.. | select(has(&quot;endpoints&quot;)).endpoints)&#39; \<br>        | yq eval &#39;del(.. | select(has(&quot;info&quot;)).info)&#39; \<br>        | yq eval &#39;del(.. | select(has(&quot;openapi&quot;)).openapi)&#39; \<br>        &gt; $2<br>}<br><br># check if we have the right java version (23) set as default<br>java --version | grep -q &quot;(build 22&quot;<br>if [ $? -ne 0 ]; then<br>  echo &quot;Java version is not 22&quot;<br>  exit 1<br>fi<br><br># start the springboot app from the jar<br>java -jar ./build/libs/drug-catalog-0.0.1-SNAPSHOT.jar &amp;<br>appPid=$!<br># wait for port 8080 to be available<br>count=0<br>while ! nc -z localhost 8080; do<br>    count=$((count+1))<br>    if [ $count -gt 10 ]; then<br>        echo &quot;Port 8080 not listening after 5 seconds&quot;<br>        exit 1<br>    else<br>        sleep 1<br>    fi<br>done<br><br>spec_path=$(realpath &#39;../specifications/drug-catalog-spec.yaml&#39;)<br>spec_file_path=$(mktemp)<br><br># remove the unwanted elements from the the yaml content and dump to tmp file   <br>remove_elements $spec_path $spec_file_path<br><br>api_file=$(mktemp)<br>api_file_path=$(mktemp)<br><br>curl -s http://localhost:8080/v3/api-docs.yaml &gt; $api_file<br># remove the unwanted elements from the the yaml content and dump to tmp file   <br>remove_elements $api_file $api_file_path<br><br># stop the springboot app<br>kill $appPid<br><br>echo<br>echo <br>echo &quot;Running oasdiff ...&quot;<br>echo<br>echo<br><br># run the oas diff tool<br>docker run --rm -t -v $spec_file_path:/var/spec-file.yaml \<br>    -v $api_file_path:/var/service-file.yaml \<br>    tufin/oasdiff diff -o \<br>    /var/spec-file.yaml  /var/service-file.yaml #&gt;&gt; /dev/null # we don&#39;t want the output<br><br>oas_status=$?<br><br>if [ $oas_status -ne 0 ]; then<br>    docker run --rm -t -v $spec_file_path:/var/spec-file.yaml \<br>        -v $api_file_path:/var/service-file.yaml \<br>        tufin/oasdiff changelog \<br>        /var/spec-file.yaml  /var/service-file.yaml<br>fi<br><br>exit $oas_status</pre><p>Now you can add this to your build script so it will be part of the build. I use Gradle, So I will share how I integrated this script into Gradle build.</p><pre>plugins {<br> id &#39;java&#39;<br> id &#39;org.springframework.boot&#39; version &#39;3.3.2&#39;<br> id &#39;io.spring.dependency-management&#39; version &#39;1.1.5&#39;<br> id &#39;org.graalvm.buildtools.native&#39; version &#39;0.10.2&#39;<br>}<br><br>group = &#39;org.gap.medium.techblogs&#39;<br>version = &#39;0.0.1-SNAPSHOT&#39;<br><br>java {<br> toolchain {<br>  languageVersion = JavaLanguageVersion.of(22)<br> }<br>}<br><br>repositories {<br> mavenCentral()<br>}<br><br>dependencies {<br> implementation &#39;org.springframework.boot:spring-boot-starter-web&#39;<br> implementation &#39;org.springframework.boot:spring-boot-starter-actuator&#39;<br> implementation &#39;org.springdoc:springdoc-openapi-starter-webmvc-api:2.6.0&#39;<br> // implementation &#39;org.springframework.boot:spring-boot-starter-data-jpa&#39;<br> // implementation &#39;org.mariadb.jdbc:mariadb-java-client&#39;<br> testImplementation &#39;org.springframework.boot:spring-boot-starter-test&#39;<br> testRuntimeOnly &#39;org.junit.platform:junit-platform-launcher&#39;<br>}<br><br>tasks.named(&#39;test&#39;) {<br> useJUnitPlatform()<br>}<br><br>task verifyOAS(type:Exec) {<br> dependsOn = [&#39;build&#39;]<br> workingDir &#39;./&#39;<br> commandLine &#39;sh&#39;, &#39;-c&#39;, &#39;./verify-oas.sh&#39;<br>}</pre><p>Now let&#39;s look at how this step will help us to find structural integrity issues. Let&#39;s see when both the implementation and specification integrity match.</p><pre> /\\ / ___&#39;_ __ _ _(_)_ __  __ _ \ \ \ \<br>( ( )\___ | &#39;_ | &#39;_| | &#39;_ \/ _` | \ \ \ \<br> \\/  ___)| |_)| | | | | || (_| |  ) ) ) )<br>  &#39;  |____| .__|_| |_|_| |_\__, | / / / /<br> =========|_|==============|___/=/_/_/_/<br><br> :: Spring Boot ::                (v3.3.2)<br><br>2024-08-24T20:53:26.717+02:00  INFO 58245 --- [drug-catalog] [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port 8080 (http) with context path &#39;/&#39;<br>2024-08-24T20:53:26.727+02:00  INFO 58245 --- [drug-catalog] [           main] o.g.m.t.d.DrugCatalogApplication         : Started DrugCatalogApplication in 1.291 seconds (process running for 1.553)<br>Connection to localhost port 8080 [tcp/http-alt] succeeded!<br>2024-08-24T20:53:27.519+02:00  INFO 58245 --- [drug-catalog] [nio-8080-exec-2] o.springdoc.api.AbstractOpenApiResource  : Init duration for springdoc-openapi is: 164 ms<br><br><br>Running oasdiff ...<br><br><br><br><br>BUILD SUCCESSFUL in 4s</pre><p>Now let&#39;s change the code to see how the build fails. Let&#39;s assume that a developer accidentally changes the search response drug list to be optional.</p><pre>public record DrugList(List&lt;Drug&gt; drugs) {<br>    <br>}</pre><p>The developer removed the @NotNull validation annotation.</p><pre>  .   ____          _            __ _ _<br> /\\ / ___&#39;_ __ _ _(_)_ __  __ _ \ \ \ \<br>( ( )\___ | &#39;_ | &#39;_| | &#39;_ \/ _` | \ \ \ \<br> \\/  ___)| |_)| | | | | || (_| |  ) ) ) )<br>  &#39;  |____| .__|_| |_|_| |_\__, | / / / /<br> =========|_|==============|___/=/_/_/_/<br><br> :: Spring Boot ::                (v3.3.2)<br><br>2024-08-24T20:59:08.219+02:00  INFO 58899 --- [drug-catalog] [           main] o.g.m.t.d.DrugCatalogApplication         : Started DrugCatalogApplication in 1.24 seconds (process running for 1.519)<br>Connection to localhost port 8080 [tcp/http-alt] succeeded!<br>2024-08-24T20:59:08.839+02:00  INFO 58899 --- [drug-catalog] [nio-8080-exec-2] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring DispatcherServlet &#39;dispatcherServlet&#39;<br><br><br>Running oasdiff ...<br><br><br>1 changes: 1 error, 0 warning, 0 info<br>error  [response-property-became-optional] at /var/service-file.yaml  <br>        in API POST /drugs/search<br>                the response property &#39;drugs&#39; became optional for the status &#39;200&#39;<br><br><br><br>&gt; Task :verifyOAS FAILED<br><br>FAILURE: Build failed with an exception.</pre><p>Now we can see that the verification task failed because we made the response drug list optional, this is a breaking change since the specification tells the consumers the drugs property of the response will be always available.</p><p>So this script together with the springboot setup will give you a very quick lightweight validation if you are making any breaking changes when you change the code. But this will not give you enough confidence that the behavior of the API is adhering to the specification. For that, you need to invest in API contract testing and API testing which will make sure that the behavior the API specification describes is kept and also aligns with the consumers’ expectations.</p><p>As promised here is the source code for the code that was mentioned in this story:</p><p><a href="https://github.com/gayanper/gap-techblog-src/tree/apps/prescription-management">GitHub - gayanper/gap-techblog-src at apps/prescription-management</a></p><p>I hope this story has given you some ideas on how you can add some validations in your build pipeline to make sure your APIs don’t accidentally break. Until the part2 of this story comes up,</p><p>Keep coding 👨‍💻 and always remember Tests before Implementation 👍</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d3ea3d4ff530" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[A Better Approach for Code Alignment]]></title>
            <link>https://medium.com/@gayanper/a-better-approach-for-code-alignment-611b520ff37e?source=rss-50d22d55ee39------2</link>
            <guid isPermaLink="false">https://medium.com/p/611b520ff37e</guid>
            <category><![CDATA[static-code-analysis]]></category>
            <category><![CDATA[platform-engineering]]></category>
            <category><![CDATA[java]]></category>
            <dc:creator><![CDATA[Gayan Perera]]></dc:creator>
            <pubDate>Sat, 06 Jul 2024 15:50:14 GMT</pubDate>
            <atom:updated>2024-07-06T15:50:14.416Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*REiAtoIoan_w196h" /><figcaption>Photo by <a href="https://unsplash.com/@edznorton?utm_source=medium&amp;utm_medium=referral">Edz Norton</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><p>The term “Code Alignment” may mean many things to many of you. The meaning of this story is about making sure implementations follow recommendations that are necessary for resilient software execution.</p><p>Now let&#39;s take some examples of such implementations,</p><ul><li>Request Authorisation</li><li>Building RESTful APIs</li><li>Setting up observability frameworks like OpenTelemetry</li><li>Setting up integration tests with Testcontainers like libraries</li></ul><p>In the above scenarios, you will find situations where you want all your developers to follow a similar way of implementing/configuring the code/library configurations. Let&#39;s take one example for each,</p><ul><li>Request Authorisation — Always validate the token before checking roles against the action</li><li>Building RESTful APIs — Always use @Produces annotation on APIs</li><li>Setting up observability frameworks like OpenTelemetry — Use OTLP Exporter for all types of data logs, metrics, and traces.</li><li>Setting up integration tests with Testcontainers like libraries — Use network aliases to avoid conflicts when running on CI Builds.</li></ul><p>Now we have some scenarios that trigger the need for <strong>Code Alignment</strong>, so let&#39;s look at different ways we can achieve it.</p><h3>Solutions</h3><h4>Shared Libraries</h4><p>This is the most common approach some developers try to solve this problem.</p><p>Let&#39;s apply this approach to each scenario and see how one could use this solution to solve it.</p><ul><li>Request Authorisation — A shared library function can be defined that will perform the token validation check the role claims and expected roles and provide a simple boolean result to notify if the action can be performed or not. This could be extended to support any used WebAPI frameworks so that this shared authorization component can be plugged in for each API as a middleware with expected roles/permissions to simplify the authorization.</li><li>Building RESTful APIs — A shared library function can be defined to configure a WebAPI endpoint with expected headers by taking in a handler function and a path that will be provided by the developer. <strong><em>This will wrap the WebAPI Library/Framework</em></strong></li><li>Setting up observability frameworks like OpenTelemetry — A shared library function can defined to perform the OpenTelemtry SDK configuration by only taking into the service name and collector endpoint. <strong><em>This will wrap the OpenTelemtry SDK</em></strong>.</li><li>Setting up integration tests with Testcontainers like libraries — A shared library function can defined to build a Testcontainer instance with given parameters. <strong><em>This will wrap the Testcontainers Library</em></strong>.</li></ul><h4>Code Templates</h4><p>You could also provide code templates so the developers can use those templates when they want to create a new service module, create a new endpoint, etc. There could be inbuilt support in your language/framework to implement this or you could look for tools that provide this support or you can invest in building one as well.</p><ul><li>Request Authorisation — This will be part of the new endpoint generation template.</li><li>Building RESTful APIs — This will be part of the new endpoint generation template.</li><li>Setting up observability frameworks like OpenTelemetry — This will be part of the new service module generation template</li><li>Setting up integration tests with Testcontainers like libraries — This will be part of the new Testcontainer instance generation template.</li></ul><p>The mileage on each scenario can differ in this approach, sometimes you might need to rely on your Editor/IDE template support as well.</p><h4>Linting/Static Analysis</h4><p>Now given all the above approaches so far either try to, Limit or Hide the underlying library options from the developer or Generate the code and forget it. While the first approaches make sure that developers will not be able to make any mistakes, The second approach just generates the correct code and trusts the developer not to make any mistakes when editing code in the future.</p><p>This approach handles this differently. It lets the developer write code using their creativity, But it also makes sure the important bits are there.</p><ul><li>Request Authorisation — At compilation time the code will be analyzed to make sure the JWT token is validated before roles/permissions are checked.</li><li>Building RESTful APIs — At compilation time the code will be analyzed to make sure the endpoint definition contains the correct header definitions that are required.</li><li>Setting up observability frameworks like OpenTelemetry — At compilation time the code will be analyzed to make sure the configuration code contains only the OLTP Expoter and it is configured.</li><li>Setting up integration tests with Testcontainers like libraries — At compilation time the code will be analyzed to make sure that each Testcontainer definition in the test code contains a network aliases setup.</li></ul><p>Now failing to find those expected important bits, could result in a compilation error or a warning based on their severity. The rules you want to enforce can be defined and maintained very similarly to a shared library. Including this analysis rules can be enforced by your CI builds to make sure each code change contains those important bits. Most of the programming language compilers support this feature or at least there are libraries supported by tech giants to build your own rules easily for those languages. We will see a simple rule implementation for the “Setting up integration tests with Testcontainers like libraries” in my story</p><p><a href="https://medium.com/@gayanper/static-code-analysis-to-the-rescue-9dab7f00b462">Static Code Analysis to the Rescue</a></p><h3>How to choose?</h3><p>None of the solutions above mentioned are <strong>silver bullets</strong>. Some of them are better for certain use cases and some of them are bad for certain use cases. Also when choosing a solution you must think about the developer experience and the technical culture you want to build in your engineering department. So let&#39;s dive into a few of the use cases and compare different solutions against each of them to see if it is a good choice. When comparing we will look into</p><ul><li>Reusability</li><li>Maintainability and Cost</li><li>Dev Experience and Culture</li></ul><h4>Request Authorisation</h4><p>Authorization is a vital part of any system. Therefore reducing the possibility of bugs in authorization is vital. The nature of such implementations is also very repetitive and looks alike. So it is a very good candidate for “Share Library” given that</p><ul><li>Identity &amp; Access Management team is a clear owner of such library and functionality</li><li>Ability to provide middleware for any WebAPI frameworks so that the consumer only needs to configure it.</li><li>Changing the Authorization strategy can be done without much rewriting of the System provided the middleware of the shared library function APIs stays backward compatible.</li></ul><p>While other solutions (Code Templates &amp; Linting) are also good candidates, they don’t address the reducing potential authorization-related bugs as the “Shared Library” solution does. Trying to capture all possible implementation variants and identify missing bits through a Linting solution could be seen as an over-engineered solution that requires a higher cost of implementation and maintenance.</p><h4>Building RESTful APIs</h4><p>Building a RESTful endpoint is already simplified by many WebAPI frameworks. So trying to write a “Shared Libary” to wrap such WebAPI framework to make sure developers return certain HTTP headers might be seen as an over-engineered solution. This could also <strong><em>reduce the developer experience</em></strong> since they are forced to use the homegrown WebAPI framework/library instead of the industry standard ones.</p><p>“Code Templates” could solve this issue partially, but since there is no guarantee that the developer will use a code template or there is no guarantee that the generated code will not be modified, the solution only solves it partially.</p><p>“Linting/Static Analysis” could be a good solution for this. Since the code that needs to be analyzed is simple and has fewer variations, it is easy to write a simple rule to capture such issues at the code compilation time. This gives instance feedback to the developer either at the time of writing the code or while compiling. Also, these checks are done always when the code is compiled.</p><p>Combing “Code Templates” &amp; “Linting/Static Analysis” will give a higher developer experience for the developers since</p><ul><li>They can keep using the standard WebAPI frameworks/libraries</li><li>They get instant feedback on the missing pieces based on the organization&#39;s coding expectations.</li><li>They can use the templates to make their coding faster.</li></ul><p>The templates and linting rules can be owned by the organization’s Platform Team or treated as an Inner Source project. Since the changes are limited to such code once implemented, not having a dedicated team for this might not be a huge issue.</p><p>Both cases <strong><em>“Setting up observability frameworks like OpenTelemetry”</em></strong> &amp; <strong><em>“Setting up integration tests with Testcontainers like libraries” </em></strong>are similar to the above usecase, therefore the solution for these use cases is also “Linting/Static Analysis” or a combination of “Code Templates” &amp; “Linting/Static Analysis”.</p><h3>Rule of Thumb</h3><p>When deciding if we should write a Share Library or Use Linting/Static Analysis tools to align our code, Always think about what you want to align</p><ol><li>Is the code we want to align critical for system functionality?</li><li>Is the code we want to align more domain-specific?</li><li>Does the code we want to align is repeated the same way in multiple places in the system?</li><li>Does hiding the implementation from the developer cause any dissatisfaction with developer empowerment?</li></ol><p>Now if the Q1 and Q3 answers are YES then you should consider using the shared library since that reduces the risk of system issues that could affect the business. If Q3 is NO then you can consider if you can handle this with <strong><em>Linting/Static Analysis tools</em></strong><em>.</em></p><p>If Q1 and Q2 and Q3 answers are NO then you should not consider the <strong><em>Share Library </em></strong>solution since that may result in high maintenance costs or over-engineered solutions.</p><p>If Q4 is YES always try to use <strong><em>Linting/Static Analysis tools, </em></strong>But evaluate with other answers, especially Q1 to make sure a linting tool failure will not cause a critical business functionality failure.</p><p>Your developers are the most valuable asset in your engineering department/organization. So keeping them motivated and empowered should be a top priority to make sure you will have a good engineering culture in your department/organization. Failing to maintain it will cause a lot of good developers to flee away from your department/organization. So take that into factor as well.</p><p>Happy Coding 👨‍💻</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=611b520ff37e" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Static Code Analysis to the Rescue]]></title>
            <link>https://medium.com/@gayanper/static-code-analysis-to-the-rescue-9dab7f00b462?source=rss-50d22d55ee39------2</link>
            <guid isPermaLink="false">https://medium.com/p/9dab7f00b462</guid>
            <category><![CDATA[code-review]]></category>
            <category><![CDATA[java]]></category>
            <category><![CDATA[static-code-analysis]]></category>
            <category><![CDATA[automation]]></category>
            <category><![CDATA[build]]></category>
            <dc:creator><![CDATA[Gayan Perera]]></dc:creator>
            <pubDate>Wed, 26 Jun 2024 17:34:30 GMT</pubDate>
            <atom:updated>2024-06-26T17:34:30.217Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*Q4znF8PVBNkDurFY" /><figcaption>Photo by <a href="https://unsplash.com/@etactics?utm_source=medium&amp;utm_medium=referral">Etactics Inc</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><p>Recently I was working with my fellow Ops Engineer to build a more developer-friendly and developer-own CI Pipeline for our new breed of modules. While we were building this we wanted to enable Testcontainers for developers in CI Pipeline so that developers can do better Automated Tests with much control over the external dependencies.</p><p>Now one struggle for us was to provide a docker daemon in the environment our builds are executing since Testcontainers need a docker API to work its magic. After some experimentation, we land on <a href="https://github.com/joyrex2001/kubedock">Kubedock</a></p><p><a href="https://github.com/joyrex2001/kubedock">GitHub - joyrex2001/kubedock: Kubedock is a minimal implementation of the docker api that will orchestrate containers on a Kubernetes cluster, rather than running containers locally.</a></p><p>Which was a better solution since our builds were running on a Kubernetes cluster. Now one hard requirement we found was that we had to use a network alias to avoid conflicting containers where two tests end up using the same container.</p><p>So we have to find a way to make sure developers always use a network alias when they configure their Testcontainer instances. A very naive approach is to use a shared library function to create a new instance of a Testcontainer. But that will limit how much Testcontainer functionality the developers can use since they will not be able to access Testcontainer API. Even if we just expose a configured Testcontainer instance, then we may need to do that for all pre-configured Testcontainer types that Testcontainers provide.</p><p>A better approach is to let developers be developers and use the Testcontainer library the way they want to use it and add a compile-time check to make sure the Testcontainer configuration is using the network alias, If it is missing the code will not be compiled.</p><p>Now different languages have different approaches to this. Following is how you can do this with Java with the help of google library</p><p><a href="https://github.com/google/error-prone">GitHub - google/error-prone: Catch common Java mistakes as compile-time errors</a></p><p>Following a simple implementation of such a linting rule and its test code</p><pre>package org.gap.java.build.rules;<br><br>import com.google.errorprone.util.ASTHelpers;<br>import com.sun.source.tree.MethodInvocationTree;<br>import com.sun.source.util.TreeScanner;<br>import com.sun.tools.javac.code.Symbol.MethodSymbol;<br><br>public class MethodTreeVisitor extends TreeScanner&lt;Void, Void&gt; {<br>    private String methodName;<br>    private boolean found = false;<br>    private boolean visited = false;<br><br>    public MethodTreeVisitor(String methodName) {<br>        this.methodName = methodName;<br>    }<br><br>    @Override<br>    public Void visitMethodInvocation(MethodInvocationTree node, Void p) {<br>        this.visited = true;<br>        if (found) {<br>            return null;<br>        }<br>        MethodSymbol symbol = ASTHelpers.getSymbol(node);<br><br>        if (symbol.getSimpleName().contentEquals(methodName)) {<br>            found = true;<br>        }<br>        return super.visitMethodInvocation(node, p);<br>    }<br><br>    public boolean isFound() {<br>        return found;<br>    }<br><br>    public boolean isVisited() {<br>        return visited;<br>    }<br>}</pre><pre>package org.gap.java.build.rules;<br><br>import java.util.List;<br><br>import com.google.auto.service.AutoService;<br>import com.google.errorprone.BugPattern;<br>import com.google.errorprone.BugPattern.SeverityLevel;<br>import com.google.errorprone.VisitorState;<br>import com.google.errorprone.bugpatterns.BugChecker;<br>import com.google.errorprone.bugpatterns.BugChecker.MethodTreeMatcher;<br>import com.google.errorprone.matchers.Description;<br>import com.google.errorprone.util.ASTHelpers;<br>import com.sun.source.tree.ExpressionStatementTree;<br>import com.sun.source.tree.MethodInvocationTree;<br>import com.sun.source.tree.MethodTree;<br>import com.sun.source.tree.StatementTree;<br>import com.sun.source.tree.Tree.Kind;<br>import com.sun.source.tree.VariableTree;<br>import com.sun.tools.javac.code.Symbol.ClassSymbol;<br>import com.sun.tools.javac.code.Type;<br>import com.sun.tools.javac.code.Types;<br>import com.sun.tools.javac.model.JavacElements;<br><br>@BugPattern(name = &quot;MustHaveNetworkAliases&quot;,<br>          summary = &quot;The withNetworkAliases method must be used with a random alias to avoid network collisions in CI.&quot;,<br>          severity = SeverityLevel.ERROR)<br>@AutoService(BugChecker.class)<br>public class KubedocNetworkAliasCheck extends BugChecker implements MethodTreeMatcher {<br>     <br>     @Override<br>     public Description matchMethod(MethodTree tree, VisitorState state) {<br>          Types types = Types.instance(state.context);<br>          JavacElements elements = JavacElements.instance(state.context);<br>          ClassSymbol typeElement = elements.getTypeElement(&quot;org.testcontainers.containers.GenericContainer&quot;);<br>          Type expectedBaseType = (Type) typeElement.asType();<br>          <br>          List&lt;? extends StatementTree&gt; statements = tree.getBody().getStatements();<br>          MethodTreeVisitor visitor = new MethodTreeVisitor(&quot;withNetworkAliases&quot;);<br>          for (StatementTree statement : statements) {<br>               switch (statement.getKind()) {<br>               case VARIABLE: {<br>                    VariableTree variableTree = (VariableTree) statement;<br>                    Type varType = ASTHelpers.getType(variableTree.getType());<br>                    if (types.isAssignable(types.erasure(varType), expectedBaseType)) {<br>                         variableTree.getInitializer().accept(visitor, null);<br>                    }<br>                    break;<br>               }<br>               case EXPRESSION_STATEMENT: {<br>                    ExpressionStatementTree expressionStatement = (ExpressionStatementTree) statement;<br>                    Type resultType = ASTHelpers.getResultType(expressionStatement.getExpression());<br>                    if (types.isAssignable(types.erasure(resultType), expectedBaseType)) {<br>                         expressionStatement.accept(visitor, null);<br>                    }<br>                    break;<br>               }<br>               default: {<br>                    // do nothing<br>               }<br>               }<br>               if (visitor.isFound()) {<br>                    break; // break out of the loop since we already found<br>                           // what we are looking for.<br>               }<br>          }<br>          if (visitor.isVisited() &amp;&amp; !visitor.isFound()) {<br>               return buildDescription(tree).setMessage(<br>                         String.format(&quot;The method %s must include a network alias on the testcontainers.&quot;, tree.getName())).build();<br>          }<br>          return Description.NO_MATCH;<br>     }<br>}</pre><pre>package org.gap.java.build.rules;<br><br>import org.junit.jupiter.api.Test;<br><br>import com.google.errorprone.CompilationTestHelper;<br><br>class KubedocNetworkAliasCheckTest {<br>    CompilationTestHelper helper = CompilationTestHelper.newInstance(KubedocNetworkAliasCheck.class, getClass());<br><br>    @Test<br>    void whenCreatedWithGenericContainerBuilderWithNetworkAliases() {<br>        helper.addSourceLines(&quot;GenericContainerCreation.java&quot;, &quot;&quot;&quot;<br>                import org.testcontainers.containers.GenericContainer;<br>                public class GenericContainerCreation {<br>                    public void setup() {<br>                        GenericContainer&lt;?&gt; genericContainer = new GenericContainer&lt;&gt;(&quot;alpine&quot;).withCommand(&quot;echo&quot;);<br>                        genericContainer.withNetworkAliases(&quot;k3s&quot;).withLabel(&quot;app&quot;, &quot;echo&quot;);<br>                        genericContainer.start();<br>                    }<br>                }<br>                &quot;&quot;&quot;.split(&quot;\n&quot;)).doTest();<br>    }<br><br>    @Test<br>    void whenCreatedWithGenericContainerBuilderWithNoNetworkAliases() {<br>        helper.addSourceLines(&quot;GenericContainerCreation.java&quot;, &quot;&quot;&quot;<br>                import org.testcontainers.containers.GenericContainer;<br>                public class GenericContainerCreation {<br>                    // BUG: Diagnostic contains: The method setup must include a network alias on the testcontainers.<br>                    public void setup() {<br>                        GenericContainer&lt;?&gt; genericContainer = new GenericContainer&lt;&gt;(&quot;alpine&quot;).withCommand(&quot;echo&quot;);<br>                        genericContainer.withLabel(&quot;app&quot;, &quot;echo&quot;);<br>                        genericContainer.start();<br>                    }<br>                }<br>                &quot;&quot;&quot;.split(&quot;\n&quot;)).doTest();<br>    }<br><br>    @Test<br>    void whenCreatedWithGenericContainerBuilderWithNoNetworkAliases_FieldVariant() {<br>        helper.addSourceLines(&quot;GenericContainerCreation.java&quot;, &quot;&quot;&quot;<br>                import org.testcontainers.containers.GenericContainer;<br>                public class GenericContainerCreation {<br>                    private GenericContainer&lt;?&gt; genericContainer;<br>                    // BUG: Diagnostic contains: The method setup must include a network alias on the testcontainers.<br>                    public void setup() {<br>                        genericContainer = new GenericContainer&lt;&gt;(&quot;alpine&quot;).withCommand(&quot;echo&quot;);<br>                        genericContainer.start();<br>                    }<br>                }<br>                &quot;&quot;&quot;.split(&quot;\n&quot;)).doTest();<br>    }<br><br>    @Test<br>    void whenNoTestContainersUsed() {<br>        helper.addSourceLines(&quot;GenericContainerCreation.java&quot;, &quot;&quot;&quot;<br>                import org.testcontainers.containers.GenericContainer;<br>                public class GenericContainerCreation {<br>                    public void setup() {<br>                        // no testcontainers used<br>                    }<br>                }<br>                &quot;&quot;&quot;.split(&quot;\n&quot;)).doTest();<br>    }<br>}</pre><p>The library provides a better way to write your rules using the <strong>Javac Model</strong> and also test your rules easily as you can see above. An example project can be found with all required configurations and the above rule code at <a href="https://github.com/gayanper/gap-techblog-src/tree/main/javac-static-analysis">https://github.com/gayanper/gap-techblog-src/tree/main/javac-static-analysis</a>. This shows how to build your rules and how you can use them in a project, in this example, the usage can be found in the <strong>“app”</strong> maven module.</p><p>To get started you can look at existing rules in the library and also follow the guide <a href="https://github.com/google/error-prone/wiki/Writing-a-check">https://github.com/google/error-prone/wiki/Writing-a-check</a>. You can get help from AI Assistants like Github Copilot and ChatGPT as well to get some idea on how to interpret certain code segments using the <strong>Javac Model</strong>.</p><p>Now next time you find a problem like this, You can choose to solve it by using a linting/static analysis solution rather than restricting the developer from using external library API.</p><p>Happing Coding 👨‍💻.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=9dab7f00b462" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[ Demystifying TDD — Part 3 (Finale)]]></title>
            <link>https://medium.com/@gayanper/demystifying-tdd-part-3-finale-60cd73440138?source=rss-50d22d55ee39------2</link>
            <guid isPermaLink="false">https://medium.com/p/60cd73440138</guid>
            <category><![CDATA[tdd]]></category>
            <category><![CDATA[automation-testing]]></category>
            <category><![CDATA[testing]]></category>
            <category><![CDATA[test-driven-development]]></category>
            <category><![CDATA[software-development]]></category>
            <dc:creator><![CDATA[Gayan Perera]]></dc:creator>
            <pubDate>Sun, 26 May 2024 17:18:19 GMT</pubDate>
            <atom:updated>2024-05-26T17:18:19.302Z</atom:updated>
            <content:encoded><![CDATA[<h3>🔍 Demystifying TDD — Part 3 (Finale)</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*Q5jMzPyPXdLqYrWY" /><figcaption>Photo by <a href="https://unsplash.com/@flowforfrank?utm_source=medium&amp;utm_medium=referral">Ferenc Almasi</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><p>Recap from parts 1 &amp; 2</p><blockquote>A lot of us have heard many time the acronym TDD in various situations of software engineering.</blockquote><blockquote>What is TDD? TDD means Test Driven Development, In the following link you can find a good explanation from <strong>Martin Fowler</strong>.<br><a href="https://martinfowler.com/bliki/TestDrivenDevelopment.html">https://martinfowler.com/bliki/TestDrivenDevelopment.html</a></blockquote><blockquote>I think most of us as software engineers know the theory behind this concept, But how many of us practice it in our day-to-day development?</blockquote><blockquote>Today I’m going to explain how I practice it <strong>close to its definition</strong>. You will see why I mean “Close to its definition” by the end of this 3 part story series.</blockquote><blockquote>We will look into 3 different setups where we can apply TDD in different ways. There are</blockquote><blockquote>- New development.</blockquote><blockquote>- Adding a new (feature to / fixing a bug in) existing code where code is testable.</blockquote><blockquote>- Adding a new (feature to / fixing a bug in ) existing code where code is not testable.</blockquote><p>We looked at how we can add tests for new feature development and when we add a feature to an existing code. That covered the first and second ways of practicing the TDD.</p><p>In this final story of this series, we will look into the third way where will practice TDD when adding functionality to an existing code base that is not designed to be <strong><em>easily testable</em></strong>.</p><h3>Adding a new (feature to / fixing a bug in ) existing code where code is not easily testable</h3><p>Our use case in part one was …</p><blockquote>Let’s take the following hypothetical example where you need to write a small program to find the count of domains that pass through your SMTP proxy service. The SMTP proxy will periodically dump email addresses when it receives emails scrapped from logs. If an email is not valid that particular entry is ignored. The counts will be pushed to a different service which provides an HTTP API to receive these counts.</blockquote><p>Now let&#39;s assume that our code was not written in an easily testable way. Now you may ask, what is the <strong>testable way</strong>?</p><p>The easiest way to put this is, that if you have written your code considering basic best coding/design practices taken into account like</p><ul><li>High cohesive</li><li>Low coupling</li><li>Inversion of Control</li></ul><p>then you should have a better code base that is easy to test. The longer version is practicing <strong>Clean Code </strong>patterns.</p><p>Now for this story, I will use the same usecase that we looked into in Part 2 with a twist of the implementation is not written using the above practices.</p><p>Recap of Part 2 use case …</p><blockquote>Now we need to add a new feature to this program that will count the emails by the country of the domain registration. All this information will be published to <strong>CountService</strong> separately using a different endpoint. To fetch domain registration, there will be a new HTTP API service that will provide the registration information which includes country code for a given list of domains.</blockquote><p>Let&#39;s look at our not easily testable code</p><pre>import java.io.BufferedReader;<br>import java.io.IOException;<br>import java.io.InputStream;<br>import java.io.InputStreamReader;<br>import java.util.HashMap;<br>import java.util.Map;<br><br>public class EmailProcessor {<br>    public EmailProcessor() {<br>    }<br>    <br>    public void processLines(InputStream stream) {<br>        Map&lt;String, Integer&gt; counts = new HashMap&lt;&gt;();<br>        try (var reader = new BufferedReader(new InputStreamReader(stream))) {<br>            var line = reader.readLine();<br>            while (line != null) {<br>                var domain = extractDomain(line);<br>                if (domain != null) {<br>                    counts.compute(domain, (currentDomain, currentCount) -&gt; {<br>                        if (currentCount != null) {<br>                            return currentCount + 1;<br>                        }<br>                        return 1;<br>                    });<br>                }<br>                line = reader.readLine();<br>            }<br>        } catch (IOException ex) {<br>            throw new IllegalArgumentException(&quot;Invalid input stream&quot;);<br>        }<br><br>        CountService.publish(counts);<br>    }<br>    <br>    private String extractDomain(String line) {<br>        var atIndex = line.indexOf(&#39;@&#39;);<br>        if (atIndex &gt; 0 &amp;&amp; atIndex &lt; (line.length() - 1) &amp;&amp; line.indexOf(&#39;.&#39;, atIndex + 1) &gt; -1) {<br>            return line.substring(atIndex + 1);<br>        }<br>        return null;<br>    }<br>}</pre><p>Now as you can see our CountService , we directly call it in a static context to publish the counts, which means if we were to write a test we need to make sure we have a running counter service endpoint since it is hard (not impossible) to mock or stub static context invocations, otherwise our execution will fail with the connection error. Here is the <strong><em>bare minimum, not production-ready</em></strong> CountService implementation for this exercise.</p><pre>import java.io.IOException;<br>import java.net.URI;<br>import java.net.http.HttpClient;<br>import java.net.http.HttpRequest;<br>import java.net.http.HttpRequest.BodyPublishers;<br>import java.net.http.HttpResponse;<br>import java.net.http.HttpResponse.BodyHandlers;<br>import java.util.Map;<br>import java.util.function.Supplier;<br><br>import com.google.gson.Gson;<br><br>public class CountService {<br>    private static final Supplier&lt;String&gt; BASE_URL = () -&gt; String.format(&quot;http://%s:%s/api&quot;,<br>            System.getProperty(&quot;countservice.host&quot;), System.getProperty(&quot;countservice.port&quot;));<br>    private static final HttpClient client = HttpClient.newHttpClient();<br>    <br>    public static void publish(Map&lt;String, Integer&gt; counts) {<br>        String url = BASE_URL.get().concat(&quot;/domains&quot;);<br>        try {<br>            String json = mapToJson(counts, &quot;domains&quot;);<br>            HttpRequest request = HttpRequest.newBuilder().uri(URI.create(url)).POST(<br>                    BodyPublishers.ofString(json)).header(&quot;Content-Type&quot;, &quot;application/json&quot;).build();<br>            HttpResponse&lt;String&gt; response = client.send(request, BodyHandlers.ofString());<br>            if (response.statusCode() != 200) {<br>                throw new IOException(&quot;Unexpected code &quot; + response.statusCode());<br>            }<br>        } catch (IOException e) {<br>            throw new IllegalStateException(e);<br>        } catch (InterruptedException e) {<br>            Thread.currentThread().interrupt();<br>            throw new IllegalStateException(e);<br>        }<br>    }<br>    <br>    private static String mapToJson(Map&lt;String, Integer&gt; map, String root) {<br>        var gson = new Gson();<br>        return gson.toJson(Map.of(root, map));<br>    }<br>}</pre><p>Now before we add our new feature, we need to make sure we add some tests to make sure our existing functionality will be preserved after the code change.</p><p>Now some developers might try to refactor code to achieve</p><ul><li>High cohesive</li><li>Low coupling</li><li>Inversion of Control</li></ul><p>while it is a good intention, But trying to refactor code without any tests to validate afterward, you are risking regressions that might only be uncovered potentially in production. So regardless you decide to refactor this code or not, you should first try to write tests to assert your current functionality. So let&#39;s see how we can do that for the given code above.</p><p>As you can see we now need to have a HTTP API server that can receive our POST request with domain count and return a successful result. Also, this server should be able to simulate an HTTP error for testing negative scenarios. For this purpose, there are multiple libraries/frameworks out there. To name a few famous ones for Java</p><ul><li>Wiremock (<a href="https://wiremock.org/">https://wiremock.org</a>)</li><li>Imposter (<a href="https://www.imposter.sh/">https://www.imposter.sh</a>)</li></ul><p>In this usecase, we will use Wiremock. Here is a small test fixture that will handle setting up and teardowning of the mock API for our count service.</p><pre>import java.io.Closeable;<br>import java.io.IOException;<br>import java.util.function.Function;<br>import java.util.function.Supplier;<br><br>import com.github.tomakehurst.wiremock.WireMockServer;<br>import com.github.tomakehurst.wiremock.client.ResponseDefinitionBuilder;<br>import com.github.tomakehurst.wiremock.client.WireMock;<br>import com.github.tomakehurst.wiremock.core.Options;<br>import com.github.tomakehurst.wiremock.matching.ContentPattern;<br>import com.github.tomakehurst.wiremock.matching.UrlPathPattern;<br><br>public final class CountServiceFixture implements Closeable {<br>    private final String path;<br>    private WireMockServer server;<br>    <br>    public CountServiceFixture(String path) {<br>        this.path = path;<br>    }<br>    <br>    public static CountServiceFixture withPath(String path) {<br>        return new CountServiceFixture(path);<br>    }<br>    <br>    public CountServiceFixture start() {<br>        server = new WireMockServer(Options.DYNAMIC_PORT);<br>        server.start();<br>        return this;<br>    }<br>    <br>    public void stub(Function&lt;String, UrlPathPattern&gt; pathBuilder, Supplier&lt;ContentPattern&lt;?&gt;&gt; requestBuilder,<br>            Function&lt;ResponseDefinitionBuilder, ResponseDefinitionBuilder&gt; responseBuilder) {<br>        var mapping = WireMock.post(pathBuilder.apply(path));<br>        mapping.withRequestBody(requestBuilder.get()).withHeader(&quot;Content-Type&quot;, WireMock.matching(&quot;application/json&quot;));<br>        mapping.willReturn(responseBuilder.apply(WireMock.aResponse().withTransformers(&quot;response-template&quot;)));<br>        server.stubFor(mapping);<br>    }<br>    <br>    public CountServiceFixture injectServerInfoAsSystemProperty() {<br>        System.setProperty(&quot;countservice.host&quot;, String.valueOf(&quot;localhost&quot;));<br>        System.setProperty(&quot;countservice.port&quot;, String.valueOf(server.port()));<br>        return this;<br>    }<br>    <br>    public WireMockServer server() {<br>        return this.server;<br>    }<br>    <br>    @Override<br>    public void close() throws IOException {<br>        if (this.server != null) {<br>            this.server.stop();<br>        }<br>    }<br>}</pre><p>Now let&#39;s write a test using this fixture for our EmailProcessor.</p><pre>import static org.junit.jupiter.api.Assertions.assertThrows;<br><br>import java.io.IOException;<br>import java.io.InputStream;<br><br>import org.junit.jupiter.api.Test;<br><br>import com.github.tomakehurst.wiremock.client.WireMock;<br><br>class EmailProcessorTest {<br>    @Test<br>    void whenAllEmailLinesAreValidExpectCountsToBePublished() {<br>        final var countDomainBody = &quot;&quot;&quot;<br>                {<br>                    &quot;domains&quot;: {<br>                        &quot;mass.com&quot;: 3,<br>                        &quot;moon.com&quot;: 2,<br>                        &quot;jupiter.com&quot;: 1<br>                    }<br>                }<br>                    &quot;&quot;&quot;;<br>        try (var countService = CountServiceFixture.withPath(&quot;/api&quot;).start().injectServerInfoAsSystemProperty()) {<br>            <br>            countService.stub(path -&gt; WireMock.urlPathEqualTo(path.concat(&quot;/domains&quot;)),<br>                    () -&gt; WireMock.equalToJson(countDomainBody), res -&gt; res.withStatus(200));<br>            <br>            var processor = new EmailProcessor();<br>            var input = EmailProcessorTest.class.getResourceAsStream(&quot;/valid-lines.txt&quot;);<br>            processor.processLines(input);<br>            <br>            countService.server().verify(1, WireMock.postRequestedFor(WireMock.urlPathEqualTo(&quot;/api/domains&quot;)));<br>        } catch (Exception e) {<br>            throw new AssertionError(e);<br>        }<br>    }<br>    <br>    @Test<br>    void whenPublishingFailsExpectTheFailureToBeReThrown() {<br>        final var countDomainBody = &quot;&quot;&quot;<br>                {<br>                    &quot;domains&quot;: {<br>                        &quot;mass.com&quot;: 3,<br>                        &quot;moon.com&quot;: 2,<br>                        &quot;jupiter.com&quot;: 1<br>                    }<br>                }<br>                    &quot;&quot;&quot;;<br>        try (var countService = CountServiceFixture.withPath(&quot;/api&quot;).start().injectServerInfoAsSystemProperty()) {<br>            <br>            countService.stub(path -&gt; WireMock.urlPathEqualTo(path.concat(&quot;/domains&quot;)),<br>                    () -&gt; WireMock.equalToJson(countDomainBody), res -&gt; res.withStatus(500));<br>            var processor = new EmailProcessor();<br>            var input = EmailProcessorTest.class.getResourceAsStream(&quot;/valid-lines.txt&quot;);<br>            assertThrows(IllegalStateException.class, () -&gt; processor.processLines(input));<br>            <br>            countService.server().verify(1, WireMock.postRequestedFor(WireMock.urlPathEqualTo(&quot;/api/domains&quot;)));<br>        } catch (Exception e) {<br>            throw new AssertionError(e);<br>        }<br>    }<br>    <br>    @Test<br>    void whenFailToReadFromStreamExpectIllegalArgumentExceptionToBeThrown() throws IOException {<br>        var processor = new EmailProcessor();<br>        var closedStream = InputStream.nullInputStream();<br>        closedStream.close();<br>        assertThrows(IllegalArgumentException.class, () -&gt; processor.processLines(closedStream));<br>    }<br>}</pre><p>Let&#39;s run the tests and see if they pass.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Oq8phHEVMqndxXAvmVK4Ig.png" /></figure><p>Yes, they <strong>PASS :)</strong></p><p>Let&#39;s try to write some tests for our new feature using the same strategy before we start changing the code to implement the feature.</p><p>Assuming we already had a DomainRegistrar implementation in this service, we will use it for this new feature as well. Here is the <strong><em>bare minimum, not production-ready</em></strong> DomainRegistrar .</p><pre>import java.io.IOException;<br>import java.net.URI;<br>import java.net.http.HttpClient;<br>import java.net.http.HttpRequest;<br>import java.net.http.HttpResponse;<br>import java.util.HashMap;<br>import java.util.List;<br>import java.util.Map;<br>import java.util.function.Supplier;<br><br>import com.google.gson.JsonObject;<br>import com.google.gson.JsonParseException;<br>import com.google.gson.JsonParser;<br><br>public class DomainRegistrar {<br>    private static final Supplier&lt;String&gt; BASE_URL = () -&gt; String.format(&quot;http://%s:%s/api&quot;,<br>            System.getProperty(&quot;domainservice.host&quot;), System.getProperty(&quot;domainservice.port&quot;));<br>    <br>    public record Registration(String domain, String countryCode) {<br>    }<br>    <br>    public static Map&lt;String, Registration&gt; fetchRegistrations(List&lt;String&gt; domains) {<br>        try (HttpClient client = HttpClient.newHttpClient()) {<br>            Map&lt;String, Registration&gt; registrations = new HashMap&lt;&gt;();<br>            <br>            for (String domain : domains) {<br>                try {<br>                    HttpResponse&lt;String&gt; response = client.send(<br>                            HttpRequest.newBuilder().uri(<br>                                    URI.create(String.format(&quot;%s/registrations/%s&quot;, BASE_URL.get(), domain))).build(),<br>                            HttpResponse.BodyHandlers.ofString());<br>                    <br>                    if (response.statusCode() == 200) {<br>                        JsonObject jsonObject = new JsonParser().parse(response.body()).getAsJsonObject();<br>                        String fetchedDomain = jsonObject.get(&quot;domain&quot;).getAsString();<br>                        String fetchedCountryCode = jsonObject.get(&quot;countryCode&quot;).getAsString();<br>                        <br>                        registrations.put(fetchedDomain, new Registration(fetchedDomain, fetchedCountryCode));<br>                    } else {<br>                        throw new IllegalStateException(&quot;Failed to fetch registration for domain: &quot; + domain<br>                                + &quot;, request endup with status code: &quot; + response);<br>                    }<br>                } catch (IOException | JsonParseException e) {<br>                    throw new IllegalStateException(e);<br>                } catch (InterruptedException e) {<br>                    Thread.currentThread().interrupt();<br>                    throw new IllegalStateException(e);<br>                }<br>            }<br>            return registrations;<br>        }<br>    }<br>}</pre><p>Now let&#39;s write a test fixture for the above</p><pre>import java.io.Closeable;<br>import java.io.IOException;<br>import java.util.function.Consumer;<br>import java.util.function.Function;<br><br>import com.github.tomakehurst.wiremock.WireMockServer;<br>import com.github.tomakehurst.wiremock.client.ResponseDefinitionBuilder;<br>import com.github.tomakehurst.wiremock.client.WireMock;<br>import com.github.tomakehurst.wiremock.core.Options;<br>import com.github.tomakehurst.wiremock.matching.UrlPathPattern;<br><br>public final class DomainRegistrarFixture implements Closeable {<br>    private final String path;<br>    private WireMockServer server;<br>    <br>    public DomainRegistrarFixture(String path) {<br>        this.path = path;<br>    }<br><br>    public static DomainRegistrarFixture withPath(String path) {<br>        return new DomainRegistrarFixture(path);<br>    }<br><br>    public DomainRegistrarFixture start() {<br>        server = new WireMockServer(Options.DYNAMIC_PORT);<br>        server.start();<br>        return this;<br>    }<br><br>    public void stub(Function&lt;String, UrlPathPattern&gt; pathBuilder, Consumer&lt;ResponseDefinitionBuilder&gt; responseBuilder) {<br>        var mapping = WireMock.get(pathBuilder.apply(path));<br>        var resBuilder = WireMock.aResponse().withTransformers(&quot;response-template&quot;);<br>        responseBuilder.accept(resBuilder);<br>        mapping.willReturn(resBuilder);<br>        server.stubFor(mapping);<br>    }<br><br>    public DomainRegistrarFixture injectServerInfoAsSystemProperty() {<br>        System.setProperty(&quot;domainservice.host&quot;, String.valueOf(&quot;localhost&quot;));<br>        System.setProperty(&quot;domainservice.port&quot;, String.valueOf(server.port()));<br>        return this;<br>    }<br><br>    public WireMockServer server() {<br>        return this.server;<br>    }<br><br>    @Override<br>    public void close() throws IOException {<br>        if(this.server != null){<br>            this.server.stop();<br>        }<br>    }<br>}</pre><p>Now let&#39;s add some tests to assert our new feature functionality to the above test case we wrote.</p><pre>import static org.junit.jupiter.api.Assertions.assertThrows;<br><br>import java.io.IOException;<br>import java.io.InputStream;<br><br>import org.junit.jupiter.api.Test;<br><br>import com.github.tomakehurst.wiremock.client.WireMock;<br><br>class EmailProcessorTest {<br>    private static final String MARS_REG_RESPONSE = &quot;&quot;&quot;<br>            {<br>                &quot;domain&quot;: &quot;mass.com&quot;,<br>                &quot;countryCode&quot;: &quot;MA&quot;<br>            }<br>            &quot;&quot;&quot;;<br>    private static final String MOON_REG_RESPONSE = &quot;&quot;&quot;<br>            {<br>                &quot;domain&quot;: &quot;moon.com&quot;,<br>                &quot;countryCode&quot;: &quot;MO&quot;<br>            }<br>            &quot;&quot;&quot;;<br>    private static final String JUPITER_REG_RESPONSE = &quot;&quot;&quot;<br>            {<br>                &quot;domain&quot;: &quot;jupiter.com&quot;,<br>                &quot;countryCode&quot;: &quot;JU&quot;<br>            }<br>            &quot;&quot;&quot;;<br>    private static final String WILDCARD_RESPONSE = &quot;&quot;&quot;<br>            {<br>                &quot;domain&quot;: &quot;{{request.path.[2]}}&quot;,<br>                &quot;countryCode&quot;: &quot;**&quot;<br>            }<br>            &quot;&quot;&quot;;<br>    <br>    @Test<br>    void whenAllEmailLinesAreValidExpectCountsToBePublished() {<br>        final var countDomainBody = &quot;&quot;&quot;<br>                {<br>                    &quot;domains&quot;: {<br>                        &quot;mass.com&quot;: 3,<br>                        &quot;moon.com&quot;: 2,<br>                        &quot;jupiter.com&quot;: 1<br>                    }<br>                }<br>                    &quot;&quot;&quot;;<br>        try (var countService = CountServiceFixture.withPath(&quot;/api&quot;).start().injectServerInfoAsSystemProperty();<br>                var domainRegService = DomainRegistrarFixture.withPath(<br>                        &quot;/api/registrations&quot;).start().injectServerInfoAsSystemProperty()) {<br>            <br>            countService.stub(path -&gt; WireMock.urlPathEqualTo(path.concat(&quot;/domains&quot;)),<br>                    () -&gt; WireMock.equalToJson(countDomainBody), res -&gt; res.withStatus(200));<br>            countService.stub(path -&gt; WireMock.urlPathEqualTo(path.concat(&quot;/countries&quot;)), () -&gt; WireMock.matching(&quot;.*&quot;),<br>                    res -&gt; res.withStatus(200));<br>            domainRegService.stub(path -&gt; WireMock.urlPathMatching(&quot;.*&quot;),<br>                    res -&gt; res.withBody(WILDCARD_RESPONSE).withStatus(200));<br>            <br>            var processor = new EmailProcessor();<br>            var input = EmailProcessorTest.class.getResourceAsStream(&quot;/valid-lines.txt&quot;);<br>            processor.processLines(input);<br>            <br>            countService.server().verify(1, WireMock.postRequestedFor(WireMock.urlPathEqualTo(&quot;/api/domains&quot;)));<br>        } catch (Exception e) {<br>            throw new AssertionError(e);<br>        }<br>    }<br>    <br>    @Test<br>    void whenPublishingFailsExpectTheFailureToBeReThrown() {<br>        final var countDomainBody = &quot;&quot;&quot;<br>                {<br>                    &quot;domains&quot;: {<br>                        &quot;mass.com&quot;: 3,<br>                        &quot;moon.com&quot;: 2,<br>                        &quot;jupiter.com&quot;: 1<br>                    }<br>                }<br>                    &quot;&quot;&quot;;<br>        try (var countService = CountServiceFixture.withPath(&quot;/api&quot;).start().injectServerInfoAsSystemProperty();<br>                var domainRegService = DomainRegistrarFixture.withPath(<br>                        &quot;/api/registrations&quot;).start().injectServerInfoAsSystemProperty()) {<br>            <br>            countService.stub(path -&gt; WireMock.urlPathEqualTo(path.concat(&quot;/domains&quot;)),<br>                    () -&gt; WireMock.equalToJson(countDomainBody), res -&gt; res.withStatus(500));<br>            var processor = new EmailProcessor();<br>            var input = EmailProcessorTest.class.getResourceAsStream(&quot;/valid-lines.txt&quot;);<br>            assertThrows(IllegalStateException.class, () -&gt; processor.processLines(input));<br>            <br>            countService.server().verify(1, WireMock.postRequestedFor(WireMock.urlPathEqualTo(&quot;/api/domains&quot;)));<br>        } catch (Exception e) {<br>            throw new AssertionError(e);<br>        }<br>    }<br>    <br>    @Test<br>    void whenFailToReadFromStreamExpectIllegalArgumentExceptionToBeThrown() throws IOException {<br>        var processor = new EmailProcessor();<br>        var closedStream = InputStream.nullInputStream();<br>        closedStream.close();<br>        assertThrows(IllegalArgumentException.class, () -&gt; processor.processLines(closedStream));<br>    }<br>    <br>    // Domain country count tests<br>    <br>    @Test<br>    void whenAllEmailLinesAreValidExpectDomainCountryCountsToBePublished() {<br>        final var countDomainBody = &quot;&quot;&quot;<br>                {<br>                    &quot;domains&quot;: {<br>                        &quot;mass.com&quot;: 3,<br>                        &quot;moon.com&quot;: 2,<br>                        &quot;jupiter.com&quot;: 1<br>                    }<br>                }<br>                    &quot;&quot;&quot;;<br>        final var countCountryBody = &quot;&quot;&quot;<br>                {<br>                    &quot;countries&quot;: {<br>                        &quot;MA&quot;: 3,<br>                        &quot;MO&quot;: 2,<br>                        &quot;JU&quot;: 1<br>                    }<br>                }<br>                    &quot;&quot;&quot;;<br>        try (var countService = CountServiceFixture.withPath(&quot;/api&quot;).start().injectServerInfoAsSystemProperty();<br>                var domainRegService = DomainRegistrarFixture.withPath(<br>                        &quot;/api/registrations&quot;).start().injectServerInfoAsSystemProperty()) {<br>            <br>            countService.stub(path -&gt; WireMock.urlPathEqualTo(path.concat(&quot;/domains&quot;)),<br>                    () -&gt; WireMock.equalToJson(countDomainBody), res -&gt; res.withStatus(200));<br>            countService.stub(path -&gt; WireMock.urlPathEqualTo(path.concat(&quot;/countries&quot;)),<br>                    () -&gt; WireMock.equalToJson(countCountryBody), res -&gt; res.withStatus(200));<br>            <br>            domainRegService.stub(path -&gt; WireMock.urlPathEqualTo(&quot;%s/mass.com&quot;.formatted(path)), res -&gt; {<br>                res.withBody(MARS_REG_RESPONSE).withHeader(&quot;Content-Type&quot;, &quot;application/json&quot;).withStatus(200);<br>            });<br>            domainRegService.stub(path -&gt; WireMock.urlPathEqualTo(&quot;%s/moon.com&quot;.formatted(path)), res -&gt; {<br>                res.withBody(MOON_REG_RESPONSE).withHeader(&quot;Content-Type&quot;, &quot;application/json&quot;).withStatus(200);<br>            });<br>            domainRegService.stub(path -&gt; WireMock.urlPathEqualTo(&quot;%s/jupiter.com&quot;.formatted(path)), res -&gt; {<br>                res.withBody(JUPITER_REG_RESPONSE).withHeader(&quot;Content-Type&quot;, &quot;application/json&quot;).withStatus(200);<br>            });<br>            <br>            var processor = new EmailProcessor();<br>            var input = EmailProcessorTest.class.getResourceAsStream(&quot;/valid-lines.txt&quot;);<br>            processor.processLines(input);<br>            <br>            countService.server().verify(1, WireMock.postRequestedFor(WireMock.urlPathEqualTo(&quot;/api/domains&quot;)));<br>            countService.server().verify(1, WireMock.postRequestedFor(WireMock.urlPathEqualTo(&quot;/api/countries&quot;)));<br>        } catch (Exception e) {<br>            throw new AssertionError(e);<br>        }<br>    }<br>    <br>    @Test<br>    void whenNoValidDomainsFoundExpectNoDomainRegistrationLookup() {<br>        try (var countService = CountServiceFixture.withPath(&quot;/api&quot;).start().injectServerInfoAsSystemProperty();<br>                var domainRegService = DomainRegistrarFixture.withPath(<br>                        &quot;/api/registrations&quot;).start().injectServerInfoAsSystemProperty()) {<br>            countService.stub(path -&gt; WireMock.urlPathMatching(&quot;.*&quot;), () -&gt; WireMock.matching(&quot;.*&quot;),<br>                    res -&gt; res.withStatus(200));<br>            <br>            var processor = new EmailProcessor();<br>            var input = EmailProcessorTest.class.getResourceAsStream(&quot;/invalid-lines.txt&quot;);<br>            <br>            processor.processLines(input);<br>            domainRegService.server().verify(0, WireMock.anyRequestedFor(WireMock.anyUrl()));<br>        } catch (Exception e) {<br>            throw new AssertionError(e);<br>        }<br>    }<br>    <br>    @Test<br>    void whenFailedToPerformDomainRegistrationsExpectTheFailureToBeReThrown() {<br>        try (var countService = CountServiceFixture.withPath(&quot;/api&quot;).start().injectServerInfoAsSystemProperty();<br>                var domainRegService = DomainRegistrarFixture.withPath(<br>                        &quot;/api/registrations&quot;).start().injectServerInfoAsSystemProperty()) {<br>            <br>            countService.stub(path -&gt; WireMock.urlPathMatching(&quot;.*&quot;), () -&gt; WireMock.matching(&quot;.*&quot;),<br>                    res -&gt; res.withStatus(200));<br>            domainRegService.stub(path -&gt; WireMock.urlPathEqualTo(&quot;%s/mass.com&quot;.formatted(path)),<br>                    res -&gt; res.withStatus(500));<br>            <br>            var processor = new EmailProcessor();<br>            var input = EmailProcessorTest.class.getResourceAsStream(&quot;/valid-lines.txt&quot;);<br>            <br>            assertThrows(IllegalStateException.class, () -&gt; processor.processLines(input));<br>            domainRegService.server().verify(WireMock.lessThan(3), WireMock.anyRequestedFor(WireMock.anyUrl()));<br>        } catch (Exception e) {<br>            throw new AssertionError(e);<br>        }<br>    }<br>    <br>    @Test<br>    void whenCountryCountPublishingFailsExpectTheFailureToBeReThrown() {<br>        final var countDomainBody = &quot;&quot;&quot;<br>                {<br>                    &quot;domains&quot;: {<br>                        &quot;mass.com&quot;: 3,<br>                        &quot;moon.com&quot;: 2,<br>                        &quot;jupiter.com&quot;: 1<br>                    }<br>                }<br>                    &quot;&quot;&quot;;<br>        final var countCountryBody = &quot;&quot;&quot;<br>                {<br>                    &quot;countries&quot;: {<br>                        &quot;MA&quot;: 3,<br>                        &quot;MO&quot;: 2,<br>                        &quot;JU&quot;: 1<br>                    }<br>                }<br>                    &quot;&quot;&quot;;<br>        <br>        try (var countService = CountServiceFixture.withPath(&quot;/api&quot;).start().injectServerInfoAsSystemProperty();<br>                var domainRegService = DomainRegistrarFixture.withPath(<br>                        &quot;/api/registrations&quot;).start().injectServerInfoAsSystemProperty()) {<br>            <br>            countService.stub(path -&gt; WireMock.urlPathEqualTo(path.concat(&quot;/domains&quot;)),<br>                    () -&gt; WireMock.equalToJson(countDomainBody), res -&gt; res.withStatus(200));<br>            countService.stub(path -&gt; WireMock.urlPathEqualTo(path.concat(&quot;/countries&quot;)),<br>                    () -&gt; WireMock.equalToJson(countCountryBody), res -&gt; res.withStatus(500));<br>            <br>            domainRegService.stub(path -&gt; WireMock.urlPathEqualTo(&quot;%s/mass.com&quot;.formatted(path)), res -&gt; {<br>                res.withBody(MARS_REG_RESPONSE).withHeader(&quot;Content-Type&quot;, &quot;application/json&quot;).withStatus(200);<br>            });<br>            domainRegService.stub(path -&gt; WireMock.urlPathEqualTo(&quot;%s/moon.com&quot;.formatted(path)), res -&gt; {<br>                res.withBody(MOON_REG_RESPONSE).withHeader(&quot;Content-Type&quot;, &quot;application/json&quot;).withStatus(200);<br>            });<br>            domainRegService.stub(path -&gt; WireMock.urlPathEqualTo(&quot;%s/jupiter.com&quot;.formatted(path)), res -&gt; {<br>                res.withBody(JUPITER_REG_RESPONSE).withHeader(&quot;Content-Type&quot;, &quot;application/json&quot;).withStatus(200);<br>            });<br>            <br>            var processor = new EmailProcessor();<br>            var input = EmailProcessorTest.class.getResourceAsStream(&quot;/valid-lines.txt&quot;);<br>            <br>            assertThrows(IllegalStateException.class, () -&gt; processor.processLines(input));<br>            domainRegService.server().verify(3, WireMock.anyRequestedFor(WireMock.anyUrl()));<br>            countService.server().verify(1, WireMock.postRequestedFor(WireMock.urlPathEqualTo(&quot;/api/countries&quot;)));<br>        } catch (Exception e) {<br>            throw new AssertionError(e);<br>        }<br>    }<br>    <br>}</pre><p>Now let&#39;s run them</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*7gc3J2BD08FYWlcrZ04jbg.png" /></figure><p>As you can see most of the new tests are failing due to our missing implementation.</p><p>Now there are some things to look after as well, for example since you are introducing new server calls to fetch domain registrations and a new country count publish call, they must be handled in our existing tests since our existing tests will run through the new feature implementation. So I have added a few HTTP API stubbing in our test methods for example</p><pre>    private static final String WILDCARD_RESPONSE = &quot;&quot;&quot;<br>            {<br>                &quot;domain&quot;: &quot;{{request.path.[2]}}&quot;,<br>                &quot;countryCode&quot;: &quot;**&quot;<br>            }<br>            &quot;&quot;&quot;;<br><br>// whenAllEmailLinesAreValidExpectCountsToBePublished<br><br>            countService.stub(path -&gt; WireMock.urlPathEqualTo(path.concat(&quot;/countries&quot;)), () -&gt; WireMock.matching(&quot;.*&quot;),<br>                    res -&gt; res.withStatus(200));<br>            domainRegService.stub(path -&gt; WireMock.urlPathMatching(&quot;.*&quot;),<br>                    res -&gt; res.withBody(WILDCARD_RESPONSE).withStatus(200));</pre><p>The above two stubbings will just let the code execute without errors by responding with an adequate response to the caller.</p><p>This type of stubbing you might figure out after you have implemented your new functionality and tried to run the tests. It is totally <strong>OK, </strong>as long as you only need to stub a few extra things in your existing functionality tests. Otherwise, it could be a hint that you should go back and check on your implementation.</p><p>Now let&#39;s add our new feature implementation into EmailProcessor.</p><pre>    // EmailProcessor.java<br><br>    public void processLines(InputStream stream) {<br>        Map&lt;String, Integer&gt; counts = new HashMap&lt;&gt;();<br>        try (var reader = new BufferedReader(new InputStreamReader(stream))) {<br>            var line = reader.readLine();<br>            while (line != null) {<br>                var domain = extractDomain(line);<br>                if (domain != null) {<br>                    counts.compute(domain, (currentDomain, currentCount) -&gt; {<br>                        if (currentCount != null) {<br>                            return currentCount + 1;<br>                        }<br>                        return 1;<br>                    });<br>                }<br>                line = reader.readLine();<br>            }<br>        } catch (IOException ex) {<br>            throw new IllegalArgumentException(&quot;Invalid input stream&quot;);<br>        }<br>        <br>        CountService.publish(counts);<br>        <br>        var domains = counts.keySet();<br>        if (!domains.isEmpty()) {<br>            var registrations = DomainRegistrar.fetchRegistrations(List.copyOf(domains));<br>            var countryCounts = new HashMap&lt;String, Integer&gt;();<br>            for (Entry&lt;String, Integer&gt; entry : counts.entrySet()) {<br>                var countryCode = registrations.get(entry.getKey()).countryCode();<br>                countryCounts.compute(countryCode, (c, count) -&gt; {<br>                    if (count == null) {<br>                        return entry.getValue();<br>                    }<br>                    return entry.getValue() + count;<br>                });<br>            }<br>            CountService.publishCountries(countryCounts);<br>        }<br>    }</pre><p>Now let&#39;s run the tests again</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/646/1*Jzh14mULjJT7pRw-7wos7Q.png" /></figure><p>Voila, all our tests pass now, this means we have implemented our new functionality as expected and also we have possibly not introduced any regressions to the existing functionality.</p><p>This exercise was just an example to show how you can practice <strong>test-driven development</strong> even without having a code base that is not designed to be easily testable. Now this test is not a theoretical <strong>unit test</strong> according to the unit-test definition in books. This test could be seen as an <strong>integration test</strong> since it integrates multiple components and tests the functionality. But in the end, it gets our main expectation satisfied, that is having tests written to “describe the functionality” that we would expect after the implementation.</p><p>Here we also choose the right tooling to simulate external HTTP APIs the way we want so that we can simulate the scenarios we want to test our implementation on. In some cases you might choose tools like Testcontainers (<a href="https://testcontainers.com/">https://testcontainers.com</a>) for things like database simulations by running a database with the fixed dataset. The success of this type of test lies in the fact that external things like HTTP API and databases can be controlled and simulated/populated by the test itself.</p><p>So after reading this 3 part series on “Demystifying TDD”, you have clear understanding how you can try TDD in practice as much as possible. 100% TDD practice is not impossible, but it is hard in certain situations, So as a Software Engineer you have to choose when you should practice TDD in your daily coding. But when you understand its value I’m pretty sure you would try as much as possible to practice it.</p><p>Happy Coding 🧑🏻‍💻</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=60cd73440138" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[ Demystifying TDD — Part 2]]></title>
            <link>https://medium.com/@gayanper/demystifying-tdd-part-2-1c151b1f5ac0?source=rss-50d22d55ee39------2</link>
            <guid isPermaLink="false">https://medium.com/p/1c151b1f5ac0</guid>
            <category><![CDATA[tdd]]></category>
            <category><![CDATA[automation-testing]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[testing]]></category>
            <category><![CDATA[test-driven-development]]></category>
            <dc:creator><![CDATA[Gayan Perera]]></dc:creator>
            <pubDate>Sun, 12 May 2024 16:18:20 GMT</pubDate>
            <atom:updated>2024-05-18T10:01:36.394Z</atom:updated>
            <content:encoded><![CDATA[<h3>🔍 Demystifying TDD — Part 2</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*tYfdZbXOe82EqRbL" /><figcaption>Photo by <a href="https://unsplash.com/@girlwithredhat?utm_source=medium&amp;utm_medium=referral">Girl with red hat</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><p>Recap from part 1 …</p><blockquote>A lot of us have heard many time the acronym TDD in various situations of software engineering.</blockquote><blockquote>What is TDD? TDD means Test Driven Development, In the following link you can find a good explanation from <strong>Martin Fowler</strong>.<br><a href="https://martinfowler.com/bliki/TestDrivenDevelopment.html">https://martinfowler.com/bliki/TestDrivenDevelopment.html</a></blockquote><blockquote>I think most of us as software engineers know the theory behind this concept, But how many of us practice it in our day-to-day development?</blockquote><blockquote>Today I’m going to explain how I practice it <strong>close to its definition</strong>. You will see why I mean “Close to its definition” by the end of this 3 part story series.</blockquote><blockquote>We will look into 3 different setups where we can apply TDD in different ways. There are</blockquote><blockquote>- New development.</blockquote><blockquote>- Adding a new (feature to / fixing a bug in) existing code where code is testable.</blockquote><blockquote>- Adding a new (feature to / fixing a bug in ) existing code where code is not testable.</blockquote><p>In this story, we will look into the second scenario where we will practice TDD when adding new functionality into existing code which is designed to be testable.</p><h3>Adding a new (feature to / fixing a bug in) existing code</h3><p>Our use case in part one was …</p><blockquote>Let’s take the following hypothetical example where you need to write a small program to find the count of domains that pass through your SMTP proxy service. The SMTP proxy will periodically dump email addresses when it receives emails scrapped from logs. If an email is not valid that particular entry is ignored. The counts will be pushed to a different service which provides an HTTP API to receive these counts.</blockquote><p>Now we need to add a new feature to this program that will count the emails by the country of the domain registration. All this information will be published to <strong>CountService</strong> separately using a different endpoint. To fetch domain registration, there will be a new HTTP API service that will provide the registration information which includes country code for a given list of domains.</p><p>Now let’s see how we can add this new feature and how we can use TDD for testing out our logic which involves counting emails by their domain’s registration country while preserving our previous counting functionality.</p><p>So with this change to practice TDD we will start by doing the same as we did in Part-1, We will have a high-level design of how we are going to implement this new feature. Such a high-level design will look like below</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/418/1*WjPWCpufqMqD6jzoB1-6OA.png" /><figcaption>high-level design</figcaption></figure><p>We have a new service that will provide domain registration information where we can get the country code in which the domain is registered. So let&#39;s add the interface of such a service into the code, where an HTTP Proxy will be implemented/generated in a real-world implementation.</p><p>Let&#39;s try to define our new service interface</p><pre>import java.util.List;<br>import java.util.Map;<br><br>public interface DomainRegistrarService {<br>    public record Registration(String domain, String countryCode) {}<br><br>    public Map&lt;String, Registration&gt; fetchRegistrations(List&lt;String&gt; domains);<br>}</pre><p>Let&#39;s do a minor refactoring to our existing Test for better stub management. I will not be using any Mock libraries to make the concept clear with this simple example. But in the real-world system, you may choose to use a Mock library to avoid a lot of stubbing implementations.</p><pre>import static org.junit.jupiter.api.Assertions.assertEquals;<br>import static org.junit.jupiter.api.Assertions.assertThrows;<br><br>import java.io.IOException;<br>import java.io.InputStream;<br>import java.util.List;<br>import java.util.Map;<br><br>import org.junit.jupiter.api.Test;<br><br>class EmailProcessorTest {<br>    private DomainRegistrarServiceStub defaultDomainRegistrarStub = new DomainRegistrarServiceStub(<br>        Map.of(&quot;mass.com&quot;, new DomainRegistrarService.Registration(&quot;mass.com&quot;, &quot;MA&quot;), &quot;moon.com&quot;,<br>                new DomainRegistrarService.Registration(&quot;moon.com&quot;, &quot;MA&quot;), &quot;jupiter.com&quot;,<br>                new DomainRegistrarService.Registration(&quot;jupiter.com&quot;, &quot;JU&quot;)),<br>        List.of(&quot;moon.com&quot;, &quot;mass.com&quot;, &quot;jupiter.com&quot;));<br><br><br>    @Test<br>    void whenAllEmailLinesAreValidExpectCountsToBePublished() {<br>        var countStub = new CountServiceStub();<br>        var processor = new EmailProcessor(countStub, defaultDomainRegistrarStub);<br>        var input = EmailProcessorTest.class.getResourceAsStream(&quot;/valid-lines.txt&quot;);<br>        <br>        processor.processLines(input);<br>        var actualCounts = countStub.domainCounts();<br>        assertEquals(3, actualCounts.get(&quot;mass.com&quot;));<br>        assertEquals(2, actualCounts.get(&quot;moon.com&quot;));<br>        assertEquals(1, actualCounts.get(&quot;jupiter.com&quot;));<br>    }<br>    <br>    @Test<br>    void whenPublishingFailsExpectTheFailureToBeReThrown() {<br>        var countStub = new CountServiceStub() {<br>            @Override<br>            public void publish(Map&lt;String, Integer&gt; counts) {<br>                throw new IllegalStateException(&quot;The service connection is broken&quot;);<br>            }<br>        };<br>        var processor = new EmailProcessor(countStub, defaultDomainRegistrarStub);<br>        var input = EmailProcessorTest.class.getResourceAsStream(&quot;/valid-lines.txt&quot;);<br>        assertThrows(IllegalStateException.class, () -&gt; processor.processLines(input));<br>    }<br>    <br>    @Test<br>    void whenFailToReadFromStreamExpectIllegalArgumentExceptionToBeThrown() throws IOException {<br>        var countStub = new CountServiceStub();<br>        var processor = new EmailProcessor(countStub, defaultDomainRegistrarStub);<br>        var closedStream = InputStream.nullInputStream();<br>        closedStream.close();<br>        assertThrows(IllegalArgumentException.class, () -&gt; processor.processLines(closedStream));<br>    }<br> <br>    private static class CountServiceStub implements CountService {<br><br>        private Map&lt;String, Integer&gt; domainCounts;<br>        private Map&lt;String, Integer&gt; countryCounts;<br><br><br>        @Override<br>        public void publish(Map&lt;String, Integer&gt; counts) {<br>            this.domainCounts = counts;<br>        }<br><br>         @Override<br>        public void publishCountries(Map&lt;String, Integer&gt; counts) {<br>            this.countryCounts = counts;<br>        }<br><br>        public Map&lt;String, Integer&gt; domainCounts() {<br>            return domainCounts;<br>        }<br><br>        public Map&lt;String, Integer&gt; countryCounts() {<br>            return countryCounts;<br>        }<br>    }<br><br>    private static class DomainRegistrarServiceStub implements DomainRegistrarService {<br>        private Map&lt;String, DomainRegistrarService.Registration&gt; expectedResult;<br>        private List&lt;String&gt; expectedInput;<br>        <br>        public DomainRegistrarServiceStub(Map&lt;String, DomainRegistrarService.Registration&gt; expectedResult,<br>                List&lt;String&gt; expectedInput) {<br>            this.expectedResult = expectedResult;<br>            this.expectedInput = expectedInput;<br>        }<br>        <br>        @Override<br>        public Map&lt;String, DomainRegistrarService.Registration&gt; fetchRegistrations(List&lt;String&gt; domains) {<br>            if (expectedInput.containsAll(domains)) {<br>                return expectedResult;<br>            }<br>            return Map.of();<br>        }<br>    }<br>}</pre><p>Now as you can see we refactored our tests by adding a new stub for CountService since now it has two types of counts we might need to assert. Also, we stubbed the DomainRegistrarService and injected it into the EmailProcessor. Now after these changes, we make sure our existing tests are passing, since we have not done any logic changes in the EmailProcessor other than the constructor change. So ideally if we have not made any mistakes in the Test classes while refactoring we should have green tests.</p><p>Now when you run the tests should pass. This indicates that the changes you did to improve the test case to add the new feature tests have not caused any issues for current functionality tests.</p><p>Now let&#39;s add the new tests for the new feature. So before jumping into the code let&#39;s plan our tests.</p><ul><li>When there are valid email domains, the country codes for those domains must be requested from DomainRegistrarService and the count for each county must be published to CountService using the count-by-country API</li><li>When there are no valid email domains, the DomainRegistrarService is not queried and no counts are published by the country</li><li>When there are valid email domains and while trying to query for country codes, if DomainRegistrarService raise any RuntimeException, those exceptions must be rethrown.</li><li>When publishing counts by country, if CountService raise any RuntimeException, those exceptions must be rethrown.</li></ul><p>Let&#39;s update our test case with the above scenarios.</p><pre>import static org.junit.jupiter.api.Assertions.assertEquals;<br>import static org.junit.jupiter.api.Assertions.assertFalse;<br>import static org.junit.jupiter.api.Assertions.assertThrows;<br><br>import java.io.IOException;<br>import java.io.InputStream;<br>import java.util.List;<br>import java.util.Map;<br>import java.util.concurrent.atomic.AtomicBoolean;<br><br>import org.junit.jupiter.api.Test;<br><br>class EmailProcessorTest {<br>    private DomainRegistrarServiceStub defaultDomainRegistrarStub = new DomainRegistrarServiceStub(<br>        Map.of(&quot;mass.com&quot;, new DomainRegistrarService.Registration(&quot;mass.com&quot;, &quot;MA&quot;), &quot;moon.com&quot;,<br>                new DomainRegistrarService.Registration(&quot;moon.com&quot;, &quot;MA&quot;), &quot;jupiter.com&quot;,<br>                new DomainRegistrarService.Registration(&quot;jupiter.com&quot;, &quot;JU&quot;)),<br>        List.of(&quot;moon.com&quot;, &quot;mass.com&quot;, &quot;jupiter.com&quot;));<br><br><br>    @Test<br>    void whenAllEmailLinesAreValidExpectCountsToBePublished() {<br>        var countStub = new CountServiceStub();<br>        var processor = new EmailProcessor(countStub, defaultDomainRegistrarStub);<br>        var input = EmailProcessorTest.class.getResourceAsStream(&quot;/valid-lines.txt&quot;);<br>        <br>        processor.processLines(input);<br>        var actualCounts = countStub.domainCounts();<br>        assertEquals(3, actualCounts.get(&quot;mass.com&quot;));<br>        assertEquals(2, actualCounts.get(&quot;moon.com&quot;));<br>        assertEquals(1, actualCounts.get(&quot;jupiter.com&quot;));<br>    }<br>    <br>    @Test<br>    void whenPublishingFailsExpectTheFailureToBeReThrown() {<br>        var countStub = new CountServiceStub() {<br>            @Override<br>            public void publish(Map&lt;String, Integer&gt; counts) {<br>                throw new IllegalStateException(&quot;The service connection is broken&quot;);<br>            }<br>        };<br>        var processor = new EmailProcessor(countStub, defaultDomainRegistrarStub);<br>        var input = EmailProcessorTest.class.getResourceAsStream(&quot;/valid-lines.txt&quot;);<br>        assertThrows(IllegalStateException.class, () -&gt; processor.processLines(input));<br>    }<br>    <br>    @Test<br>    void whenFailToReadFromStreamExpectIllegalArgumentExceptionToBeThrown() throws IOException {<br>        var countStub = new CountServiceStub();<br>        var processor = new EmailProcessor(countStub, defaultDomainRegistrarStub);<br>        var closedStream = InputStream.nullInputStream();<br>        closedStream.close();<br>        assertThrows(IllegalArgumentException.class, () -&gt; processor.processLines(closedStream));<br>    }<br>    <br>    // Domain country count tests<br>    <br>    @Test<br>    void whenAllEmailLinesAreValidExpectDomainCountryCountsToBePublished() {<br>        var countStub = new CountServiceStub();<br>        var processor = new EmailProcessor(countStub, defaultDomainRegistrarStub);<br>        var input = EmailProcessorTest.class.getResourceAsStream(&quot;/valid-lines.txt&quot;);<br>        <br>        processor.processLines(input);<br>        var actualCounts = countStub.countryCounts();<br>        assertEquals(5, actualCounts.get(&quot;MA&quot;));<br>        assertEquals(1, actualCounts.get(&quot;JU&quot;));<br>    }<br><br>    @Test<br>    void whenNoValidDomainsFoundExpectNoDomainRegistrationLookup() {<br>        var invocationAssertion = new AtomicBoolean(false);<br>        var domainRegistrarStub = new DomainRegistrarService() {<br>            @Override<br>            public Map&lt;String, DomainRegistrarService.Registration&gt; fetchRegistrations(List&lt;String&gt; domains) {<br>                invocationAssertion.set(true);<br>                return Map.of();<br>            }<br>        };<br>        var countStub = new CountServiceStub();<br>        var processor = new EmailProcessor(countStub, domainRegistrarStub);<br>        var input = EmailProcessorTest.class.getResourceAsStream(&quot;/invalid-lines.txt&quot;);<br>        <br>        processor.processLines(input);<br>        assertFalse(invocationAssertion.get());<br>    }<br><br>    @Test<br>    void whenFailedToPerformDomainRegistrationsExpectTheFailureToBeReThrown() {<br>        var domainRegistrarStub = new DomainRegistrarService() {<br>            @Override<br>            public Map&lt;String, DomainRegistrarService.Registration&gt; fetchRegistrations(List&lt;String&gt; domains) {<br>                throw new IllegalStateException(&quot;service unavailable&quot;);<br>            }<br>        };<br>        var countStub = new CountServiceStub();<br>        var processor = new EmailProcessor(countStub, domainRegistrarStub);<br>        var input = EmailProcessorTest.class.getResourceAsStream(&quot;/valid-lines.txt&quot;);<br>        <br>        assertThrows(IllegalStateException.class, () -&gt; processor.processLines(input));<br>    }<br><br>    @Test<br>    void whenCountryCountPublishingFailsExpectTheFailureToBeReThrown() {<br>        var countStub = new CountServiceStub() {<br>            @Override<br>            public void publishCountries(Map&lt;String, Integer&gt; counts) {<br>                throw new IllegalStateException(&quot;service unavailable&quot;);<br>            }<br>        };<br>        var processor = new EmailProcessor(countStub, defaultDomainRegistrarStub);<br>        var input = EmailProcessorTest.class.getResourceAsStream(&quot;/valid-lines.txt&quot;);<br>        <br>        assertThrows(IllegalStateException.class, () -&gt; processor.processLines(input));<br>    }<br><br>    // Stubs are removed here<br>}</pre><p>Now if you focus on the new test methods after // Domain country count tests the line comment, you can see the new test cases for new functionality. In the real world, we might add more tests to cover edge cases, but for this exercise, we keep the scenarios we cover to a limited number.</p><p>Now if you run the tests you will see a test report similar to below</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*zGpI4wMgUH506Wbu8MR_-g.png" /><figcaption>VSCode Test Results</figcaption></figure><p>As you can see 3 new scenarios are failing as expected since we have yet to implement them. One scenario whenNoValidDomainsFoundExpectNoDomainRegistrationLookupdoes pass since the current code also works as expected. But we need to make sure it pass even after the implementation is done.</p><p>Let&#39;s change the code and add the new feature.</p><pre>import java.io.BufferedReader;<br>import java.io.IOException;<br>import java.io.InputStream;<br>import java.io.InputStreamReader;<br>import java.util.HashMap;<br>import java.util.List;<br>import java.util.Map;<br>import java.util.Map.Entry;<br><br>public class EmailProcessor {<br>    private CountService countService;<br>    private DomainRegistrarService domainRegistrarService;<br>    <br>    public EmailProcessor(CountService countService, DomainRegistrarService domainRegistrarService) {<br>        this.countService = countService;<br>        this.domainRegistrarService = domainRegistrarService;<br>    }<br>    <br>    public void processLines(InputStream stream) {<br>        Map&lt;String, Integer&gt; counts = new HashMap&lt;&gt;();<br>        try (var reader = new BufferedReader(new InputStreamReader(stream))) {<br>            var line = reader.readLine();<br>            while (line != null) {<br>                var domain = extractDomain(line);<br>                if (domain != null) {<br>                    counts.compute(domain, (currentDomain, currentCount) -&gt; {<br>                        if (currentCount != null) {<br>                            return currentCount + 1;<br>                        }<br>                        return 1;<br>                    });<br>                }<br>                line = reader.readLine();<br>            }<br>        } catch (IOException ex) {<br>            throw new IllegalArgumentException(&quot;Invalid input stream&quot;);<br>        }<br><br>        countService.publish(counts);<br><br>        var domains = counts.keySet();<br>        if (!domains.isEmpty()) {<br>            var registrations = domainRegistrarService.fetchRegistrations(List.copyOf(domains));<br>            var countryCounts = new HashMap&lt;String, Integer&gt;();<br>            for (Entry&lt;String, Integer&gt; entry : counts.entrySet()) {<br>                var countryCode = registrations.get(entry.getKey()).countryCode();<br>                countryCounts.compute(countryCode, (c, count) -&gt; {<br>                    if(count == null) {<br>                        return entry.getValue();<br>                    }<br>                    return entry.getValue() + count;<br>                });<br>            }<br>            countService.publishCountries(countryCounts);      <br>        }<br>    }<br>    <br>    private String extractDomain(String line) {<br>        var atIndex = line.indexOf(&#39;@&#39;);<br>        if (atIndex &gt; 0 &amp;&amp; atIndex &lt; (line.length() - 1) &amp;&amp; line.indexOf(&#39;.&#39;, atIndex + 1) &gt; -1) {<br>            return line.substring(atIndex + 1);<br>        }<br>        return null;<br>    }<br>}</pre><p>Now let&#39;s run the tests again</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*rE7dJ4ig-mWVXokAOkzIFA.png" /><figcaption>VSCode Test Results</figcaption></figure><p>As you can see all our tests pass, <strong>which implies that given that our tests are correct</strong> <strong>and accurate,</strong> our implementation is correct and has no unforeseen side effects to existing functionality.</p><h4>Some Additional Notes</h4><p>Now if you compare the implementation in Part-1 and here in Part-2, you will see I also fixed the bug, the error handling is not correct according to the original contract we defined.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*OGOrqwQqPIUL6j3JySaeyA.png" /><figcaption>Code Diff</figcaption></figure><p>As you can see I removed the try-catch surrounding publish invocation on the CountService to make sure we let the original Runtime error be thrown up to the caller. Now we might have caught this in our original tests If we tested with a different type of runtime error which is closer to the actual CounterService implementation. This is something you always need to remember when working with stubs,</p><blockquote><strong>Always use returns values, input values, and errors more closer to the domain of the component being stubbed.</strong></blockquote><p>Now back to Part-2, So you see that if the code is testable, you can easily practice TDD by</p><ul><li>First, make the required changes such as injecting the required components into the component under test.</li><li>Second, make changes to your existing tests to adapt to the changes you did in previous step if needed, and make sure your tests run and they pass.</li><li>Third, Add the new test cases for the new functionality and make sure those tests give you the correct result (<em>most of the time fail</em>) for missing implementation.</li><li>Last, Implement your new feature and rerun the tests, This time all tests should be green.</li></ul><p>Now with this approach, you can be more confident about your changes and you can spend less time testing the feature manually.</p><p>So I hope now know how you can practice TDD as <strong>close to its definition </strong>next time you want to add a new feature to an existing code base.</p><p>Happy Coding 🧑🏻‍💻</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1c151b1f5ac0" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[ Demystifying TDD — Part 1]]></title>
            <link>https://medium.com/@gayanper/demystifying-tdd-part-1-b3df3c0acc90?source=rss-50d22d55ee39------2</link>
            <guid isPermaLink="false">https://medium.com/p/b3df3c0acc90</guid>
            <category><![CDATA[tdd]]></category>
            <category><![CDATA[testing]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[test-driven-development]]></category>
            <category><![CDATA[automatetest]]></category>
            <dc:creator><![CDATA[Gayan Perera]]></dc:creator>
            <pubDate>Thu, 09 May 2024 16:36:53 GMT</pubDate>
            <atom:updated>2024-05-09T16:36:53.847Z</atom:updated>
            <content:encoded><![CDATA[<h3>🔍 Demystifying TDD — Part 1</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*kxKgdFcKrRXwTgqe" /><figcaption>Photo by <a href="https://unsplash.com/@hansreniers?utm_source=medium&amp;utm_medium=referral">Hans Reniers</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><p>A lot of us have heard many time the acronym TDD in various situations of software engineering.</p><p>What is TDD? TDD means Test Driven Development, In the following link you can find a good explanation from <strong>Martin Fowler</strong>.</p><p><a href="https://martinfowler.com/bliki/TestDrivenDevelopment.html">bliki: Test Driven Development</a></p><p>I think most of us as software engineers know the theory behind this concept, But how many of us practice it in our day-to-day development?</p><p>Today I’m going to explain how I practice it <strong>close to its definition</strong>. You will see why I mean “Close to its definition” by the end of this 3 part story series.</p><p>We will look into 3 different setups where we can apply TDD in different ways. There are</p><ul><li>New development.</li><li>Adding a new (feature to / fixing a bug in) existing code where code is testable.</li><li>Adding a new (feature to / fixing a bug in ) existing code where code is not testable.</li></ul><p>In the current story, we will look into the first part where we practice TDD with new development.</p><h3>New Development</h3><p>Let&#39;s take the following hypothetical example where you need to write a small program to find the count of domains that pass through your SMTP proxy service. The SMTP proxy will periodically dump email addresses when it receives emails scrapped from logs. If an email is not valid that particular entry is ignored. The counts will be pushed to a different service which provides an HTTP API to receive these counts.</p><p>Now let&#39;s see how we can write this program and how we can use TDD for testing out our logic which involve counting domains form given emails.</p><p>To practice TDD you must start with a design-first approach than a code-first approach. This doesn’t mean you need to draw all the UML diagrams like Sequence, Class, etc. But you need to at least have a design for your approach in your mind so that you can use that to set up your program components which can be used to write the tests according to the components contracts.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/232/1*lSkzQYCy6G-5cVWRVjsofg.png" /><figcaption>high-level design</figcaption></figure><p>Now as we can see above, we decided to have a <strong>FileStream</strong> which will provide the file content as a stream into our <strong>EmailProcessor</strong>, and at the end of processing we will push all count information to <strong>CountService</strong> which takes care of pushing the data into another service over a HTTP API.</p><p>Let try to implement using Java,</p><pre>// ------------ CountService.java<br>import java.util.Map;<br><br>public interface CountService {<br>    void publish(Map&lt;String, Integer&gt; counts)<br>}<br><br><br>// ------------ EmailProcessor.java <br>import java.io.InputStream;<br><br>public class EmailProcessor {<br>    private CountService countService;<br><br>    public EmailProcessor(CountService countService) {<br>        this.countService = countService;<br>    }<br><br><br>    public void processLines(InputStream stream) {<br><br>    }<br>}</pre><p>Now as you can see we have the skeleton for our component. So let’s try to identify the test scenarios we have to test</p><ul><li>When the provided InputStream can be read and all email lines are valid, expect counts to be published to CountService based on the input email lines and their domains.</li><li>When the provided InputStream can be read and some email lines don’t seem to be valid emails, expect the counts to be published by ignoring those invalid email lines.</li><li>When the provided InputStream can be read and some email lines don’t seem to be valid domains, expect the counts to be published by ignoring those invalid domain lines.</li><li>When the provided InputStream cannot be read, raise an InvalidArgumentExpcetion</li><li>When publishing counts, if CountService raise any RuntimeException, those exceptions must be rethrown.</li></ul><p>Ok Now let&#39;s try to write tests for the above scenarios. Now you might be thinking how are we going to use test stubs for FileInputStream and CountService right?</p><p>Well in this scenario, we can easily mock/stub the CountService since we know it has a simple contract. But the FileInputStream is a different beast, trying to mock or stub it will make our tests more dependent on the implementation of our logic. Which might need to change every time we change the way we interact with the FileInputStream. Therefore in such situations, we could just use a few files which has different inputs according to the test scenarios and use them.</p><p>Let&#39;s see how to do that in Java using JUnit</p><pre>// ------------ EmailProcessorTest.java<br>import static org.junit.jupiter.api.Assertions.assertEquals;<br>import static org.junit.jupiter.api.Assertions.assertThrows;<br><br>import java.io.IOException;<br>import java.io.InputStream;<br>import java.util.HashMap;<br>import java.util.Map;<br><br>import org.junit.jupiter.api.Test;<br><br>class EmailProcessorTest {<br>    @Test<br>    void whenAllEmailLinesAreValidExpectCountsToBePublished() {<br>        var actualCounts = new HashMap&lt;String, Integer&gt;();<br>        var processor = new EmailProcessor(new CountService() {<br>            @Override<br>            public void publish(Map&lt;String, Integer&gt; counts) {<br>                actualCounts.putAll(counts);<br>            }<br>        });<br>        var input = EmailProcessorTest.class.getResourceAsStream(&quot;/valid-lines.txt&quot;);<br><br>        processor.processLines(input);<br>        assertEquals(3, actualCounts.get(&quot;mass.com&quot;));<br>        assertEquals(2, actualCounts.get(&quot;moon.com&quot;));<br>        assertEquals(1, actualCounts.get(&quot;jupiter.com&quot;));<br>    }<br><br>    @Test<br>    void whenPublishingFailsExpectTheFailureToBeReThrown() {<br>        var processor = new EmailProcessor(new CountService() {<br>            @Override<br>            public void publish(Map&lt;String, Integer&gt; counts) {<br>                throw new IllegalStateException(&quot;The service connection is broken&quot;);<br>            }<br>        });<br>        var input = EmailProcessorTest.class.getResourceAsStream(&quot;/valid-lines.txt&quot;);<br>        assertThrows(IllegalStateException.class, () -&gt; processor.processLines(input));<br>    }<br><br>    @Test<br>    void whenFailToReadFromStreamExpectIllegalArgumentExceptionToBeThrown() throws IOException {<br>        var processor = new EmailProcessor(new CountService() {<br>            @Override<br>            public void publish(Map&lt;String, Integer&gt; counts) {<br>            }<br>        });<br>        var closedStream = InputStream.nullInputStream();<br>        closedStream.close();<br>        assertThrows(IllegalArgumentException.class, () -&gt; processor.processLines(closedStream));<br>    }<br>}</pre><pre>// ------------ valid-lines.txt<br><br>life@mass.com<br>life@moon.com<br>alien@mass.com<br>martian@mass.com<br>accending@jupiter.com<br>landing@moon.comtex</pre><p>Now we have some tests that are failing, Our target should be to pass them by implementing the EmailProcessor. I have not written all test scenarios, But I hope the above example tests give you an idea.</p><p>So here is a very preliminary implementation done according to the above tests.</p><pre>import java.io.BufferedReader;<br>import java.io.IOException;<br>import java.io.InputStream;<br>import java.io.InputStreamReader;<br>import java.util.HashMap;<br>import java.util.Map;<br><br>public class EmailProcessor {<br>    private CountService countService;<br>    <br>    public EmailProcessor(CountService countService) {<br>        this.countService = countService;<br>    }<br>    <br>    public void processLines(InputStream stream) {<br>        Map&lt;String, Integer&gt; counts = new HashMap&lt;&gt;();<br>        try (var reader = new BufferedReader(new InputStreamReader(stream))) {<br>            var line = reader.readLine();<br>            while (line != null) {<br>                var domain = extractDomain(line);<br>                if (domain != null) {<br>                    counts.compute(domain, (currentDomain, currentCount) -&gt; {<br>                        if (currentCount != null) {<br>                            return currentCount + 1;<br>                        }<br>                        return 1;<br>                    });<br>                }<br>                line = reader.readLine();<br>            }<br>        } catch (IOException ex) {<br>            throw new IllegalArgumentException(&quot;Invalid input stream&quot;);<br>        }<br><br>        try {<br>            countService.publish(counts);<br>        } catch (RuntimeException ex) {<br>            throw new IllegalStateException(&quot;connection not available&quot;);<br>        }<br>    }<br>    <br>    private String extractDomain(String line) {<br>        var atIndex = line.indexOf(&#39;@&#39;);<br>        if (atIndex &gt; 0 &amp;&amp; atIndex &lt; (line.length() - 1) &amp;&amp; line.indexOf(&#39;.&#39;, atIndex + 1) &gt; -1) {<br>            return line.substring(atIndex + 1);<br>        }<br>        return null;<br>    }<br>}</pre><p>Now in the above tests you can use mocking libraries like <a href="https://github.com/mockito/mockito">Mockito</a> instead of building the test stubs our selfs for the CountService . For Assertion, you could use assertion libraries like <a href="https://assertj.github.io/doc/">AssertJ</a>.</p><p>Now this kind of unit test writing cannot be done for all scenarios. For example, if you are implementing a DAO or a Repository that talks to a database using JDBC or some sort of Database client, then it will be really tedious to mock such components. Similar to the InputStream in this example. Therefore in such situations, we might need to deviate from the Unittest guidelines such as</p><blockquote>The component under test must be tested in islotation</blockquote><p>Here we have used a classpath resource stream to provide the required file contents for our tests. It&#39;s a balancing act of making the design closer to the problem we are solving while making the code testable as <strong>in isolation</strong> as possible.</p><p>So I hope you now know how you can practice TDD as <strong>close to its definition </strong>next time you do a new development.</p><p>Happy Coding 🧑🏻‍💻</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b3df3c0acc90" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>