Full Width [alt+shift+f] Shortcuts [alt+shift+k]
Sign Up [alt+shift+s] Log In [alt+shift+l]
49
This blog post is another one in the ‘writing things down to structure my thinking on where I want my career to go’ series. I will get back to writing technical and automation blog posts soon, but I need to finish my contract testing course first. One of the things I like to do most in life is traveling and seeing new places. Well, seeing new places, mostly, as the novelty of waiting, flying and staying in hotel rooms has definitely worn off by now. I am in the privileged position (really, that is what it is: I’m privileged, and I fully realize that) that I get to scratch this travel itch professionally on a regular basis these days. Over the last few years, I have been invited to contribute to meetups and conferences abroad, and I also get to run in-house training sessions with companies outside the Netherlands a couple of times per year. Most of this traveling takes place within Europe, but for the last three years, I have been able to travel outside of Europe once every year (South...
5 months ago

Improve your reading experience

Logged in users get linked directly to articles resulting in a better reading experience. Please login for free, it takes less than 1 minute.

More from On Test Automation

Building and improving Page Objects, one step at a time

A few weeks ago, I ran a pair programming / mentoring session with someone who reached out to me because they felt they could use some support. When I first saw the code they wrote, I was pretty impressed. Sure, there were some things I would have done differently, but most of that was personal preference, not a matter of my way being better than their way objectively. Instead of working on their code directly, instead, we therefore decided to build up some test code together from zero, discussing and applying good programming principles and patterns along the way. As the tests were using Playwright in TypeScript, and were heavily oriented towards using the graphical user interface, we decided to start building a Page Object-based structure for a key component in their application. This component was a UI component that enabled an end user to create a report in the system. The exact type of system or even the domain itself isn’t really important for the purpose of this blog post, by the way. The component looked somewhat like this, heavily simplified: At the top, there was a radiobutton with three options that selected different report layouts. Every report layout consists of multiple form fields, and most form fields are text areas plus lock buttons that open a dropdown-like structure where you can edit the permissions for that field by selecting one or more roles that can view the contents of that text field (this is a privacy feature). And of course, there’s a save button to save the report, as well as a print button. The actual UI component had a few other types of components, but for the sake of brevity, let’s stick to these for now. Iteration 0 - creating an initial Page Object My approach whenever I start from scratch, either on my own or when working with someone else, is to take small steps and gradually introduce complexity. It might be tempting to immediately create a Page Object containing fields for all the elements and methods to interact with them, but that is going to get messy very quickly. Instead, we started with the simplest Page Object we could think of: one that allowed us to create a standard report, without considering the lock buttons to set permissions. Let’s assume that a standard report consists of only a title and a summary text field. The first iteration of that Page Object turned out to look something like this: export class StandardReportPage { readonly page: Page; readonly radioSelectStandard: Locator; readonly textfieldTitle: Locator; readonly textfieldSummary: Locator; readonly buttonSaveReport: Locator; readonly buttonPrintReport: Locator; constructor(page: Page) { this.page = page; this.radioSelectStandard = page.getByLabel('Standard report'); this.textfieldTitle = page.getByPlaceholder('Title'); this.textfieldSummary = page.getByPlaceholder('Summary'); this.buttonSaveReport = page.getByRole('button', { name: 'Save' }); this.buttonPrintReport = page.getByRole('button', { name: 'Print' }); } async select() { await this.radioSelectStandard.click(); } async setTitle(title: string) { await this.textfieldTitle.fill(title); } async setSummary(summary: string) { await this.textfieldSummary.fill(summary); } async save() { await this.buttonSaveReport.click(); } async print() { await this.buttonPrintReport.click(); } } which makes the test using this Page Object look like this: test('Creating a standard report', async ({ page } ) => { const standardReportPage = new StandardReportPage(page); await standardReportPage.select(); await standardReportPage.setTitle('My new report title'); await standardReportPage.setSummary('Summary of the report'); await standardReportPage.save(); await expect(page.getByTestId('standard-report-save-success')).toBeVisible(); }); Iteration 1 - grouping element interactions My first question after we implemented and used this Page Object was: ‘how do you feel about the readability of this test?’. Of course, we just wrote this code, and it’s a small example, but imagine you’re working with Page Objects that are all written like this, and offer many more element interactions. This will quickly lead to very procedural test code ‘enter this, enter that, click here, check there’ that doesn’t show the intent of the test very clearly. In other words, this coding style does not really do a great job of hiding the implementation of the page (even when it hides the locators) and focusing only on behaviour. To improve this, I suggested grouping element interactions that form a logical end user interaction together in a single method and expose that. When I read or write a test, I’m not particularly interested in the sequence of individual element interactions I need to execute to perform a higher-level action. I’m not interested in ‘filling a text field’ or ‘clicking a button’, I’m interested in ‘creating a standard report’. This led us to refactor the Page Object into this: export class StandardReportPage { readonly page: Page; readonly radioSelectStandard: Locator; readonly textfieldTitle: Locator; readonly textfieldSummary: Locator; readonly buttonSaveReport: Locator; readonly buttonPrintReport: Locator; constructor(page: Page) { this.page = page; this.radioSelectStandard = page.getByLabel('Standard report'); this.textfieldTitle = page.getByPlaceholder('Title'); this.textfieldSummary = page.getByPlaceholder('Summary'); this.buttonSaveReport = page.getByRole('button', { name: 'Save' }); this.buttonPrintReport = page.getByRole('button', { name: 'Print' }); } async select() { await this.radioSelectStandard.click(); } async create(title: string, summary: string) { await this.textfieldTitle.fill(title); await this.textfieldSummary.fill(summary); await this.buttonSaveReport.click(); } async print() { await this.buttonPrintReport.click(); } } which in turn made the test look like this: test('Creating a standard report', async ({ page } ) => { const standardReportPage = new StandardReportPage(page); await standardReportPage.select(); await standardReportPage.create('My new report title', 'Summary of the report'); await expect(page.getByTestId('standard-report-save-success')).toBeVisible(); }); Much better already when it comes to readability and ‘expose behaviour, hide implementation’. Doing exactly this is not something that is unique to UI automation, or even to test automation in general, by the way. This principle is called encapsulation, and it is one of the fundamental principles of object-oriented programming. It is a principle that is very useful to know when you’re writing test code, if you want to keep your code readable, that is. Iteration 2 - Adding the ability to set permissions on a form field For our next step, we decided to introduce the ability to set the access permissions for every text field. As explained and shown in the graphical representation of the form at the top of this post, every form field in the standard form has an associated lock button that opens a small dialog where the user can select which user roles can and cannot see the report field. Our initial idea was to simply add additional fields in the Page Object representing the standard report. However, that would lead to a lot of repetitive work and to the standard report having a lot of fields containing element locators. So, we decided to see if we could consider the combination of a report text field and the associated permission lock button as a Page Component, i.e., a separate class that encapsulates the behaviour of a group of related elements on a specific page. Setting this up in a reusable manner will be a lot easier when the HTML for these Page Components has the same structure across the entire application. The good news is that this is often the case, especially when frontend designers and developers design and implement frontends using tools like Storybook. So, the relevant part of the HTML for the standard form might look like this (again, simplified): <div id="standard_form"> <div data-testid="form_field_subject"> <div data-testid="form_field_subject_textfield"></div> <div data-testid="form_field_subject_lock"></div> </div> <div data-testid="form_field_summary"> <div data-testid="form_field_summary_textfield"></div> <div data-testid="form_field_summary_lock"></div> </div> </div> An example reusable Page Component class might then look something like this: export class ReportFormField { readonly page: Page; readonly textfield: Locator; readonly buttonLockPermissions: Locator; constructor(page: Page, formFieldName: string) { this.page = page; this.textfield = page.getByTestId(`${formFieldName}_textfield`); this.buttonLockPermissions = page.getByTestId(`${formFieldName}_lock`); } async complete(text: string, roles: string[]) { await this.textfield.fill(text); await this.buttonLockPermissions.click(); // handle setting permissions for the form field } } Note how the constructor of this Page Component class uses (in fact, relies on) the predictable, repetitive structure of the component in the application and the presence of data-testid attributes. If your components do not have these, find a way to add them, or find another generic way to locate the individual elements in the component on the page. Now that we have defined our Page Component class, we need to define the relationship between these Page Components and the Page Object that contains them. In the past, my choice would default to creating base Page classes that would contain the reusable Page Components, as well as other utility methods. The more specific Page Object would then inherit from these base Pages, allowing them to use the methods defined in the parent base Page class. Almost invariably, at some point that would lead to very messy base Page classes, with lots of fields and methods in it that were only tangentially related, at best. The cause of this mess? Me not thinking clearly about the type of the relation between different Page Objects and Components. You see, creating base classes and using inheritance for reusability creates ‘is-a’ relations. These are useful when the relation between objects is of an ‘is-a’ nature. However, in our case, there is no ‘is-a’ relation, there is a ‘has-a’ relation. A Page Object has a certain Page Component. In other words, we need to define the relationship a different way, and that’s by using composition instead of inheritance. We define Page Components as components of our Page Objects, which makes for a far more natural relationship between the two, and for code that is way more clearly structured: export class StandardReportPage { readonly page: Page; readonly radioSelectStandard: Locator; readonly reportFormFieldTitle: ReportFormField; readonly reportFormFieldSummary: ReportFormField; readonly buttonSaveReport: Locator; readonly buttonPrintReport: Locator; constructor(page: Page) { this.page = page; this.radioSelectStandard = page.getByLabel('Standard report'); this.reportFormFieldTitle = new ReportFormField(this.page, 'title'); this.reportFormFieldSummary = new ReportFormField(this.page, 'summary'); this.buttonSaveReport = page.getByRole('button', { name: 'Save' }); this.buttonPrintReport = page.getByRole('button', { name: 'Print' }); } async select() { await this.radioSelectStandard.click(); } async create(title: string, summary: string, roles: string[]) { await this.reportFormFieldTitle.complete(title, roles); await this.reportFormFieldSummary.complete(summary, roles); await this.buttonSaveReport.click(); } async print() { await this.buttonPrintReport.click(); } } Reading this code feels far more natural than cramming everything into one or more parent classes c.q. base page objects. Lesson learned here: the way objects are related in your code should reflect the relationship between these objects in real life, that is, in your application. Iteration 3 - What about the other report types? The development and refactoring steps we have gone through so far led us to a point where we were pretty happy with the code. However, we still only have Page Objects for a single type of form, and as you have seen in the sketch at the top of this blog post, there are different types of forms. How do we deal with those? Especially when we know that these forms share some components and behaviour, but not all of them? It is tempting to immediately jump to conclusions and start throwing patterns and structures at the problem, but in pair programming sessions like this, I typically try and avoid finding and implementing the ‘final’ solution right away. Why? Because the best learning is done when you see (or create, in this case) a suboptimal situation, discuss the problems with that situation, investigate potential solutions and only then implement them. Sure, it will take longer, initially, but this is made up for in spades with a much better understanding of what suboptimal code looks like and how to improve it. So, first we create separate classes for individual report types, each similar to the implementation for the standard report we created before. Here is an example for an extended report, containing more form fields (well, just one more, but you get the idea): export class ExtendedReportPage { readonly page: Page; readonly radioSelectExtended: Locator; readonly reportFormFieldTitle: ReportFormField; readonly reportFormFieldSummary: ReportFormField; readonly reportFormFieldAdditionalInfo: ReportFormField; readonly buttonSaveReport: Locator; readonly buttonPrintReport: Locator; constructor(page: Page) { this.page = page; this.radioSelectExtended = page.getByLabel('Extended report'); this.reportFormFieldTitle = new ReportFormField(this.page, 'title'); this.reportFormFieldSummary = new ReportFormField(this.page, 'summary'); this.reportFormFieldAdditionalInfo = new ReportFormField(this.page, 'additionalInfo'); this.buttonSaveReport = page.getByRole('button', { name: 'Save' }); this.buttonPrintReport = page.getByRole('button', { name: 'Print' }); } async select() { await this.radioSelectExtended.click(); } async create(title: string, summary: string, additionalInfo: string, roles: string[]) { await this.reportFormFieldTitle.complete(title, roles); await this.reportFormFieldSummary.complete(summary, roles); await this.reportFormFieldAdditionalInfo.complete(additionalInfo, roles); await this.buttonSaveReport.click(); } async print() { await this.buttonPrintReport.click(); } } Obviously, there’s a good amount of duplication between this class and the Page Object for the standard report. What to do with them? Contrary to the situation with the Page Components, it is a good idea to reduce the duplication by creating a base report Page Object here. We’re talking about creating an ‘is-a’ relationship (inheritance) here, not a ‘has-a’ relation (composition). A standard report is a report. That means that in this case, we can, and we should, create a base report Page Object, move some (or maybe even all) of the duplicated code there, and have the specific report Page Objects derive from that base report class. My recommendation here is to make the base report Page Object an abstract class to prevent people from instantiating it directly. This leads to more expressive and clear code, as we can only instantiate the concrete report subtype, which will make it immediately clear to the reader of the code what type of report they’re dealing with. In the abstract class, we declare the elements that are shared between all reports. This applies to methods, but also to web elements that appear in all report types. This is what the abstract base class might look like: export abstract class ReportBasePage { readonly page: Page; readonly reportFormFieldTitle: ReportFormField; readonly reportFormFieldSummary: ReportFormField; readonly buttonSaveReport: Locator; readonly buttonPrintReport: Locator; abstract readonly radioSelect: Locator; protected constructor(page: Page) { this.page = page; this.reportFormFieldTitle = new ReportFormField(this.page, 'title'); this.reportFormFieldSummary = new ReportFormField(this.page, 'summary'); this.buttonSaveReport = page.getByRole('button', { name: 'Save' }); this.buttonPrintReport = page.getByRole('button', { name: 'Print' }); } async select() { await this.radioSelect.click(); } async print() { await this.buttonPrintReport.click(); } } and a concrete class for the standard report, implementing the abstract class now looks like this: export class ExtendedReportPage extends ReportBasePage { readonly page: Page; readonly radioSelect: Locator; readonly reportFormFieldAdditionalInfo: ReportFormField; constructor(page: Page) { super(page); this.page = page; this.radioSelect = page.getByLabel('Extended report'); this.reportFormFieldAdditionalInfo = new ReportFormField(this.page, 'additionalInfo'); } async create(title: string, summary: string, additionalInfo: string, roles: string[]) { await this.reportFormFieldTitle.complete(title, roles); await this.reportFormFieldSummary.complete(summary, roles); await this.reportFormFieldAdditionalInfo.complete(additionalInfo, roles); await this.buttonSaveReport.click(); } } The abstract class takes care of the methods that are shared between all reports, such as the print() and the select() methods, It also defines what elements and methods should be implemented by the implementing concrete classes. For now, that’s only the radioSelect locator. Note that at the moment, because the data required for the different types of reports is not the same, we cannot yet add an abstract select(): void method requirement, that all report Page Objects should implement, to our abstract class. This is a temporary drawback and one that we will address in a moment. Also note that the test code doesn’t change, but we can now create both a standard report and an extended report that, behind the scenes, share a significant amount of code. Definitely a step in the right direction. Iteration 4 - Dealing with test data Our tests already look pretty good. They are easy to read, and the way the code is structured aligns with the structure of the parts of the application they’re representing. Are we done yet? Well, maybe. As a final improvement to our tests, let’s have a look at the way we handle our test data. Right now, the test data we use in our test methods is simply an unstructured collection of strings, integers, boolean and so on. For small tests and a simple domain that is easy to understand, you might get away with this, but as soon as your test suite grows and your domain becomes more complex, this will get confusing. What does that string value represent exactly? Why is that variable a boolean and what happens if it is set to true (or false)? This is where test data objects can help out. Test data objects are simple classes, often nothing more fancy than a Data Transfer Object (DTO), that represent a domain entity. In this situation, that domain entity might be a report, for example. Having types that represent domain entities greatly improves the readability of our code, it will make it much easier to understand what exactly we’re doing here. The implementation of these test data objects is often straightforward. In TypeScript, we can use a simple interface for this purpose. I chose to create one ReportContent class that contains the data for all of our report types. As they diverge, I might choose to refactor these into separate interfaces, but for now, this is fine. Also, defining this test data object has the additional benefit of allowing me to move the definition of the create() method for the different report Page Objects to the abstract base class, a step that we were unable to perform previously. This is what my interface looks like: export interface ReportContent { title: string; summary: string; additionalInfo?: string; roles: string[]; } The additionalInfo field is marked as optional, as it only appears in an extended report, not in a standard report. In some cases, to further improve flexibility and readability of our code, we might add a builder or a factory that helps us create instances of our test data objects using a fluent syntax. This also allows us to set sensible default values for properties to avoid having to assign the same values to these properties in every test. In this specific case, that’s not really necessary, because object creation based on an interface in TypeScript is really straightforward, and our ReportContent object is small, anyway. Your mileage may vary. Now that we have defined a type for our report data, we can change the signature and the implementation of the create() methods in our Page Objects to use this type. Here’s an example for the extended report: async create(report: ReportContent) { await this.reportFormFieldTitle.complete(report.title, report.roles); await this.reportFormFieldSummary.complete(report.summary, report.roles); await this.reportFormFieldAdditionalInfo.complete(report.additionalInfo, report.roles); await this.buttonSaveReport.click(); } and we can now add the following line to the abstract ReportBasePage class: abstract create(report: ReportContent): void; to enforce all report Page Objects to implement a create() method that takes an argument of type ReportContent. We can do the same for other test data objects. Oh, and if you’re storing your tests in the same repository as your application code, these test data objects might even exist already, in which case you might be able to reuse them. This is definitely worth checking, because why would we reinvent the wheel? That was a lot of work, but it has led to code that is, in my opinion, well-structured and easy to read and maintain. As this blog post has hopefully shown, it is very useful to have a good working knowledge of common object-oriented programming principles and patterns when you’re writing test code. This is especially true for UI automation, but many of the principles we have seen in this blog post can be applied to other types of test automation, too. There are many other patterns out there to explore. This blog post is not an attempt to list them all, nor does it show ‘the one true way’ of writing Page Objects. Hopefully, though, it has shown you my thought process when I write test automation code, and how understanding fundamentals of object-oriented programming helps me do this better. A massive ‘thank you’ to Olena for participating in the pair programming session I discussed and for reviewing this blog post. I really appreciate it.

3 months ago 29 votes
My terms and conditions for using AI

Last weekend, I wrote a more or less casual post on LinkedIn containing the ‘rules’ (it’s more of a list of terms and conditions, really) I set for myself when it comes to using AI. That post received some interesting comments that made me think and refine my thoughts on when (not) to use AI to support me in my work. Thank you to all of you who commented for doing so, and for showing me that there still is value in being active on LinkedIn in between all the AI-generated ‘content’. I really appreciate it. Now, AI and LLMs like ChatGPT or Claude can be very useful, that is, when used prudently. I think it is very important to be conscious and cautious when it comes to using AI, though, which is why I wrote that post. I wrote it mostly for myself, to structure my thoughts around AI, but also because I think it is important that others are at least conscious of what they’re doing and working with. That doesn’t mean you have to adhere to or even agree with my views and the way I use these tools, by the way. Different strokes for different folks. Because of the ephemeral nature of these LinkedIn posts, and the importance of the topic to me, I want to repeat the ‘rules’ (again, more of a T&C list) I wrote down here. This is the original, unchanged list from the post I wrote on February 15: I only use it to support me in completing tasks I understand. I need to be able to scrutinize the output the AI system produces and see if it is both sound and fit for the purpose I want to use it for. I never use it to explain to me something I don’t know yet or don’t understand enough. I have seen and read about too many hallucinations to trust them to teach me what I don’t understand. Instead, I use books, articles, and other content from authors and sources I do trust if I’m looking to learn something new. I never EVER use it for creative work. I don’t use AI-generated images anywhere, and all of my blogs, LinkedIn posts, comments, course material and other written text are 100% my own, warts and all. My views, my ideas, my voice. Interestingly, most of the comments were written in reaction to the first two bullet points at the time I wrote this blog post. I don’t know exactly why this is the case, it might be because the people who read it agree (which I doubt seeing the tsunami of AI-generated content that’s around these days), or maybe because there’s a bit of stigma around admitting to use AI for content generation. I don’t know. What I do know is that it is an important principle to me. I wrote about the reasons for that in an earlier blog post, so I won’t repeat myself here. Like so many terms and conditions, the list I wrote down in this post will probably evolve over time, but what will not change is me remaining very careful around where I use and where I don’t use AI to help me in my work. Especially now that the speed with which new developments in the AI space are presented to us and the claims around what it can and will do only get bigger, I think it is wise to remain cautious and look at these developments with a critical and very much human view.

4 months ago 35 votes
Improving the tests for RestAssured.Net with mutation testing and Stryker.NET

When I build and release new features or bug fixes for RestAssured.Net, I rely heavily on the acceptance tests that I wrote over time. Next to serving as living documentation for the library, I run these tests both locally and on every push to GitHub to see if I didn’t accidentally break something, for different versions of .NET. But how reliable are these tests really? Can I trust them to pass and fail when they should? Did I cover all the things that are important? I speak, write and teach about the importance of testing your tests on a regular basis, so it makes sense to start walking the talk and get more insight into the quality of the RestAssured.Net test suite. One approach to learning more about the quality of your tests is through a technique called mutation testing. I speak about and demo testing your tests and using mutation testing to do so on a regular basis (you can watch a recent talk here), but until now, I’ve pretty much exclusively used PITest for Java. As RestAssured.Net is a C# library, I can’t use PITest, but I’d heard many good things about Stryker.NET, so this would be a perfect opportunity to finally use it. Adding Stryker.NET to the RestAssured.Net project The first step was to add Stryker.Net to the RestAssured.Net project. Stryker.NET is a dotnet tool, so installing it is straightforward: run dotnet new tool-manifest to create a new, project-specific tool manifest (this was the first local dotnet tool for this project) and then dotnet tool install dotnet-stryker to add Stryker.NET as a dotnet tool to the project. Running mutation tests for the first time Running mutation tests with Stryker.NET is just as straightforward: dotnet stryker --project RestAssured.Net.csproj from the tests project folder is all it takes. Because both my test suite (about 200 tests) and the project itself are relatively small code bases, and because my test suite runs quickly, running mutation tests for my entire project works for me. It still took around five minutes for the process to complete. If you have a larger code base, and longer-running test suites, you’ll see that mutation testing will take much, much longer. In that case, it’s probably best to start on a subset of your code base and a subset of your test suite. After five minutes and change, the results are in: Stryker.NET created 538 mutants from my application code base. Of these: 390 were killed, that is, at least one test failed because of this mutation, 117 survived, that is, the change did not make any of the tests fail, and 31 resulted in a timeout, which I’ll need to investigate further, but I suspect it has something to do with HTTP timeouts (RestAssured.Net is an HTTP API testing library, and all acceptance tests perform actual HTTP requests) This leads to an overall mutation testing score of 59.97%. Is that good? Is that bad? In all honesty, I don’t know, and I don’t care. Just like with code coverage, I am not a fan of setting fixed targets for this type of metric, as these will typically lead to writing tests for the sake of improving a score rather than for actual improvement of the code. What I am much more interested in is the information that Stryker.NET produced during the mutation testing process. Opening the HTML report I was surprised to see that out of the box, Stryker.NET produces a very good-looking and incredibly helpful HTML report. It provides both a high-level overview of the results: as well as in-depth detail for every mutant that was killed or that survived. It offers a breakdown of the results per namespace and per class, and it is the starting point for further drilling down into results for individual mutants. Let’s have a look and see if the report provides some useful, actionable information for us to improve the RestAssured.Net test suite. Missing coverage Like many other mutation testing tools, Stryker.NET provides code coverage information along with mutation coverage information. That is, if there is code in the application code base that was mutated, but that is not covered by any of the tests, Stryker.NET will inform you about it. Here’s an example: Stryker.NET changed the message of an exception thrown when RestAssured.Net is asked to deserialize a response body that is either null or empty. Apparently, there is no test in the test suite that covers this path in the code. As this particular code path deals with exception handling, it’s probably a good idea to add a test for it: [Test] public void EmptyResponseBodyThrowsTheExpectedException() { var de = Assert.Throws<DeserializationException>(() => { Location responseLocation = (Location)Given() .When() .Get($"{MOCK_SERVER_BASE_URL}/empty-response-body") .DeserializeTo(typeof(Location)); }); Assert.That(de?.Message, Is.EqualTo("Response content is null or empty.")); } I added the corresponding test in this commit. Removed code blocks Another type of mutant that Stryker.NET generates is the removal of a code block. Going by the mutation testing report, it seems like there are a few of these mutants that are not detected by any of the tests. Here’s an example: The return statement for the Put() method body, which is used to perform an HTTP PUT operation, is replaced with an empty method body, but this is not picked up by any of the tests. The same applies to the methods for HTTP PATCH, DELETE, HEAD and OPTIONS. Looking at the tests that cover the different HTTP verbs, this makes sense. While I do call each of these HTTP methods in a test, I don’t assert on the result for the aforementioned HTTP verbs. I am basically relying on the fact that no exception is thrown when I call Put() when I say ‘it works’. Let’s change that by at least asserting on a property of the response that is returned when these HTTP verbs are used: [Test] public void HttpPutCanBeUsed() { Given() .When() .Put($"{MOCK_SERVER_BASE_URL}/http-put") .Then() .StatusCode(200); } These assertions were added to the RestAssured.Net test suite in this commit. Improving testability The next signal I received from this initial mutation testing run is an interesting one. It tells me that even though I have acceptance tests that add cookies to the request and that only pass when the request contains the cookies I set, I’m not properly covering some logic that I added: To understand what is going on here, it is useful to know that a Cookie in C# offers a constructor that creates a Cookie specifying only a name and a value, but that a cookie has to have a domain value set. To enforce that, I added the logic you see in the screenshot. However, Stryker.NET tells me I’m not properly testing this logic, because changing its implementation doesn’t cause any tests to fail. Now, I might be able to test this specific logic with a few added acceptance tests, but it really is only a small piece of logic, and I should be able to test that logic in isolation, right? Well, not with the code written in the way it currently is… So, time to extract that piece of logic into a class of its own, which will improve both the modularity of the code and allow me to test it in isolation. First, let’s extract the logic into a CookieUtils class: internal class CookieUtils { internal Cookie SetDomainFor(Cookie cookie, string hostname) { if (string.IsNullOrEmpty(cookie.Domain)) { cookie.Domain = hostname; } return cookie; } } I deliberately made this class internal as I don’t want it to be directly accessible to RestAssured.Net users. However, as I do need to access it in the tests, I have to add this little snippet to the RestAssured.Net.csproj file: <ItemGroup> <InternalsVisibleTo Include="$(MSBuildProjectName).Tests" /> </ItemGroup> Now, I can add unit tests that should cover both paths in the SetDomainFor() logic: [Test] public void CookieDomainIsSetToDefaultValueWhenNotSpecified() { Cookie cookie = new Cookie("cookie_name", "cookie_value"); CookieUtils cookieUtils = new CookieUtils(); cookie = cookieUtils.SetDomainFor(cookie, "localhost"); Assert.That(cookie.Domain, Is.EqualTo("localhost")); } [Test] public void CookieDomainIsUnchangedWhenSpecifiedAlready() { Cookie cookie = new Cookie("cookie_name", "cookie_value", "/my_path", "strawberry.com"); CookieUtils cookieUtils = new CookieUtils(); cookie = cookieUtils.SetDomainFor(cookie, "localhost"); Assert.That(cookie.Domain, Is.EqualTo("strawberry.com")); } These changes were added to the RestAssured.Net source and test code in this commit. An interesting mutation So far, all the signals that appeared in the mutation testing report generated by Stryker.NET have been valuable, as in: they have pointed me at code that isn’t covered by any tests yet, to tests that could be improved, and they have led to code refactoring to improve testability. Using Stryker.NET (and mutation testing in general) does sometimes lead to some, well, interesting mutations, like this one: I’m checking that a certain string is either null or an empty string, and if either condition is true, RestAssured.Net throws an exception. Perfectly valid. However, Stryker.NET changes the logical OR to a logical AND (a common mutation), which makes it impossible for the condition to evaluate to true. Is that even a useful mutation to make? Well, to some extent, it is. Even if the code doesn’t make sense anymore after it has been mutated, it does tell you that your tests for this logical condition probably need some improvement. In this case, I don’t have to add more tests, as we discussed this exact statement earlier (remember that it had no test coverage at all). It did make me look at this statement once again, though, and I only then realized that I could simplify this code snippet to if (string.IsNullOrEmpty(responseBodyAsString)) { throw new DeserializationException("Response content is null or empty."); } Instead of a custom-built logical OR, I am now using a construct built into C#, which is arguably the safer choice. In general, if your mutation testing tool generates several (or even many) mutants for the same code statement or block, it might be a good idea to have another look at that code and see if it can be simplified. This was just a very small example, but I think this observation holds true in general. This change was added to the RestAssured.Net source and test code in this commit. Running mutation tests again and inspecting the results Now that several (supposed) improvements to the tests and the code have been made, let’s run the mutation tests another time to see if the changes improved our score. In short: 397 mutants were killed now, up from 390 (that’s good) 111 mutants survived, down from 117 (that’s also good) there were 32 timeouts, up from 31 (that needs some further investigation) Overall, the mutation testing score went up from 59,97% to 61,11%. This might not seem like much, but it is definitely a step in the right direction. The most important thing for me right now is that my tests for RestAssured.Net have improved, my code has improved and I learned a lot about mutation testing and Stryker.NET in the process. Am I going to run mutation tests every time I make a change? Probably not. There is quite a lot of information to go through, and that takes time, time that I don’t want to spend for every build. For that reason, I’m also not going to make these mutation tests part of the build and test pipeline for RestAssured.Net, at least not any time soon. This was nonetheless both a very valuable and a very enjoyable exercise, and I’ll definitely keep improving the tests and the code for RestAssured.Net using the suggestions that Stryker.NET presents.

5 months ago 44 votes
My career and a thought experiment

As is the case every year, 2025 is starting off relatively slowly. There’s not a lot of training courses to run yet, and since a few of the projects I worked on wrapped up in December, I find myself with a little bit of extra time and headspace on my hands. I actually enjoy these slower moments, because they give me some time to think about where my professional career is going, if I’m still happy with the direction it is going on, and what I would like to see changed. Last year, I quit doing full time projects as an individual contributor to development teams in favour of part-time consultancy work and more focus on my training services. 2024 has been a great year overall, and I would be happy to continue working in this way in 2025. However, as a thought experiment, I took some time to think about what it would take for me to go back to full time roles, or maybe (maybe!) even consider joining a company on a permanent basis. Please note that this post is not intended as an ‘I need a job!’ cry for help. My pipeline for 2025 is slowly but surely filling up, and again, I am very happy with the direction my career is going at the moment. However, I have learned that it never hurts to leave your options open, and even though I love the variety in my working days these days, I think I would enjoy working with one team, on one goal, for an extended amount of time, too, under the right conditions. If nothing else, this post might serve as a reference post to send to people and companies that reach out to me with a full time contract opportunity or even a permanent job opening. This is also not a list of requirements that is set in stone. As my views on what would make a great job change (and they will), I will update this post to reflect those views. So, to even consider joining a company on a full-time contract or even a permanent basis, there are basically three things I will and should consider: What does the job look like? What will I be doing on a day-to-day basis? What are the must-haves regarding terms and conditions? What are the nice to haves that would provide the icing on the cake for me? Let’s take a closer look at each of these things. What I look for in a job As I mentioned before, I am not looking for a job as an individual contributor to a development team. I have done that for many years, and it does not really give me the energy that it used to. On the other hand, I am definitely not looking for a hands-off, managerial kind of role, as I’d like to think I would make an atrocious manager. Plus, I simply enjoy being hands-on and writing code way too much to let that go. I would like to be responsible for designing and implementing the testing and automation strategy for a product I believe in. It would be a lead role, but, as mentioned, with plenty (as in daily) opportunities to get hands-on and contribute to the code. The work would have to be technically and mentally challenging enough to keep me motivated in the long term. Getting bored quickly is something I suffer from, which is the main driver behind only doing part-time projects and working on multiple different things in parallel right now. I don’t want to work for a consultancy and be ‘farmed out’ to their clients. I’ve done that pretty much my entire career, and if that’s what the job will look like, I’d rather keep working the way I’m working now. The must-haves There are (quite) a few things that are non-negotiable for me to even consider joining a company full time, no matter if it’s on a contract or a permanent basis. The pay must be excellent. Let’s not beat around the bush here: people work to make money. I do, too. I’m doing very well right now, and I don’t want that to change. The company should be output-focused, as in they don’t care when I work, how many hours I put in and where I work from, as long as the job gets done. I am sort of spoiled by my current way of working, I fully realise that, but I’ve grown to love the flexibility. By the way, please don’t read ‘flexible’ as ‘working willy-nilly’. Most work is not done in a vacuum, and you will have to coordinate with others. The key word here is ‘balance’. Collaboration should be part of the company culture. I enjoy working in pair programming and pair testing setups. What I do not like are pointless meetings, and that includes having Scrum ceremonies ‘just because’. The company should be a remote-first company. I don’t mind the occasional office day, but I value my time too much to spend hours per week on commuting. I’ve done that for years, and it is time I’ll never get back. The company should actively stimulate me contributing to conferences and meetups. Public speaking is an important part of my career at the moment, and I get a lot of value from it. I don’t want to give that up. There should be plenty of opportunities for teaching others. This is what I do for a living right now, I really enjoy it, and I’d like to think I’m pretty good at it, too. Just like with the public speaking, I don’t want to give that up. This teaching can take many forms, though. Running workshops and regular pairing with others are just two examples. The job should scratch my travel itch. I travel abroad for work on average about 5-6 times per year these days, and I would like to keep doing that, as I get a lot of energy from seeing different places and meeting people. Please note that ‘traveling’ and ‘commuting’ are two completely different things. Yes, I realize this is quite a long list, but I really enjoy my career at the moment, and there are a lot of aspects to it that I’m not ready to give up. The nice to haves There are also some things that are not strictly necessary, but would be very nice to have in a job or full time contract: The opportunity to continue working on side gigs. I have a few returning customers that I’ve been working with for years, and I would really appreciate the opportunity to continue doing that. I realise that I would have to give up some things, but there are a few clients that I would really like to keep working with. By the way, this is only a nice to have for permanent jobs. For contracting gigs, it is a must-have. It would be very nice if the technology stack that the company is using is based on C#. I’ve been doing quite a bit of work in this stack over the years and I would like to go even deeper. If the travel itch I mentioned under the must-haves could be scratched with regular travel to Canada, Norway or South Africa, three of my favourite destinations in the world, that would be a very big plus. I realize that the list of requirements above is a long one. I don’t think there is a single job out there that ticks all the boxes. But, again, I really like what I’m doing at the moment, and most of the boxes are ticked at the moment. I would absolutely consider going full time with a client or even an employer, but I want it to be a step forward, not a step back. After all, this is mostly a thought experiment at the moment, and until that perfect contract or job comes along, I’ll happily continue what I’m doing right now.

5 months ago 62 votes

More in programming

Single-Use Disposable Applications

As search gets worse and “working code” gets cheaper, apps get easier to make from scratch than to find.

13 hours ago 4 votes
Thoughts on Motivation and My 40-Year Career

I’ve never published an essay quite like this. I’ve written about my life before, reams of stuff actually, because that’s how I process what I think, but never for public consumption. I’ve been pushing myself to write more lately because my co-authors and I have a whole fucking book to write between now and October. […]

8 hours ago 3 votes
Desktop UI frameworks written by a single person

Less known desktop UI frameworks Writing desktop software is hard. The UI technologies of Windows or MacOS are awful compared to web technology. What can trivially be done with HTML/CSS/JavaScript in few minutes can take hours using Windows’s win32 APIs or Mac’s Cocoa. That’s why the default technology for desktop apps, especially cross-platform, is Electron: a Chrome browser combined with Node runtime. The problem is that it’s bloaty: each app is a unique build of Chrome with a little bit of application code. Chrome is over 100MB so many apps ship less than 1MB of code in a 100M wrapper. People tried to address the problem of poor OS APIs by writing UI frameworks, often meant to be cross-platform. You’ve heard about QT, GTK, wxWindows. The problem with those is that they are also old, their APIs are not the greatest either and they are bloaty as well. There just doesn’t seem to be a good option. Writing your own framework seems impossible due to the size of task. But is it? I’ll show a couple of less-known UI frameworks written mostly be a single person, often done simply to enable writing an application. SWELL in WDL WDL is interesting. Justin Frankel, the guy who created Winamp, has a repository of C++ code he uses in different projects. After selling Winamp to AOL, a side quest of writing file sharing application, getting fired from AOL for writing file sharing application, he started a company building Reaper a digital audio workstation software for Windows. Winamp is a win32 API program and so is Reaper. At some point Justin decided to make a Mac version but by then he had a lot of code heavily using win32 APIs. So he did what anyone in his position would: he implemented win32 APIs for Mac OS and Linux and called it SWELL - Simple Windows Emulation Layer. Ok, actually no-one else would do it. It was an insane idea but it worked. It’s important to not over-state SWELL capabilities. It’s not Wine. You can’t take any win32 program and recompile for Mac with SWELL. Frankel is insanely pragmatic and so is his code. SWELL only implements the subset of APIs he uses in Reaper. At the same time Reaper is a big app so if SWELL works for Reaper, it could work for your app. WDL is open-source using permissive MIT license. Sublime Text For a few years Sublime Text was THE programmer’s editor. It was written by a single developer in C++ and he wrote a custom UI toolkit for it. Not open source but its existence shows it can be done. RAD Debugger RAD Debugger is an open-source Windows debugger for C/C++ apps written in C by mostly a single person. It implements a custom UI framework based on 3D renderer. The UI is integral part of the the app but the code is well structured so you probably can take just their UI / render code and use it in your own C / C++ app. Currently the app / UI is only for Windows but it’s designed to be cross-platform and they are working on porting the renderer to Mac OS / Linux. They use permissive MIT license and everything is written in C. Dear ImGUI Dear ImGui is a newer cross-platform, UI framework in C++. Open source, permissive MIT license. Written by mostly a single person. Ghostty Ghostty is a cross-platform terminal emulator and UI. It’s written in Zig by mostly a single person and uses it’s own low-level GPU renderer for the UI. You too can write your own UI framework At first the idea of writing your own UI framework seems impossibly daunting. What I’m hoping to show is that if you’re ambitious enough it’s possible to build cross platform desktop apps that are not just bloated 100MB Chrome wrappers around few kilobytes of custom code. I’m not saying it’s a simple thing, just that enough people did it that it’s possible. It shouldn’t be necessary but both Microsoft and Apple have tragically dropped the ball on providing decent, high-performance UI libraries for their OS. Microsoft even writes their own apps, like Teams, in web technologies. Thanks to open source you’re not at the staring line. You can just use Dear ImGUI or WDL’s SWELL. Or you can extract the UI code from RAD Debugger or Ghostty (if you write in Zig). Or you can look at how their implementation to speed up your own design and implementation.

yesterday 2 votes
Logic for Programmers Turns One

I released Logic for Programmers exactly one year ago today. It feels weird to celebrate the anniversary of something that isn't 1.0 yet, but software projects have a proud tradition of celebrating a dozen anniversaries before 1.0. I wanted to share about what's changed in the past year and the work for the next six+ months. The Road to 0.1 I had been noodling on the idea of a logic book since the pandemic. The first time I wrote about it on the newsletter was in 2021! Then I said that it would be done by June and would be "under 50 pages". The idea was to cover logic as a "soft skill" that helped you think about things like requirements and stuff. That version sucked. If you want to see how much it sucked, I put it up on Patreon. Then I slept on the next draft for three years. Then in 2024 a lot of business fell through and I had a lot of free time, so with the help of Saul Pwanson I rewrote the book. This time I emphasized breadth over depth, trying to cover a lot more techniques. I also decided to self-publish it instead of pitching it to a publisher. Not going the traditional route would mean I would be responsible for paying for editing, advertising, graphic design etc, but I hoped that would be compensated by much higher royalties. It also meant I could release the book in early access and use early sales to fund further improvements. So I wrote up a draft in Sphinx, compiled it to LaTeX, and uploaded the PDF to leanpub. That was in June 2024. Since then I kept to a monthly cadence of updates, missing once in November (short-notice contract) and once last month (Systems Distributed). The book's now on v0.10. What's changed? A LOT v0.1 was very obviously an alpha, and I have made a lot of improvements since then. For one, the book no longer looks like a Sphinx manual. Compare! Also, the content is very, very different. v0.1 was 19,000 words, v.10 is 31,000.1 This comes from new chapters on TLA+, constraint/SMT solving, logic programming, and major expansions to the existing chapters. Originally, "Simplifying Conditionals" was 600 words. Six hundred words! It almost fit in two pages! The chapter is now 2600 words, now covering condition lifting, quantifier manipulation, helper predicates, and set optimizations. All the other chapters have either gotten similar facelifts or are scheduled to get facelifts. The last big change is the addition of book assets. Originally you had to manually copy over all of the code to try it out, which is a problem when there are samples in eight distinct languages! Now there are ready-to-go examples for each chapter, with instructions on how to set up each programming environment. This is also nice because it gives me breaks from writing to code instead. How did the book do? Leanpub's all-time visualizations are terrible, so I'll just give the summary: 1180 copies sold, $18,241 in royalties. That's a lot of money for something that isn't fully out yet! By comparison, Practical TLA+ has made me less than half of that, despite selling over 5x as many books. Self-publishing was the right choice! In that time I've paid about $400 for the book cover (worth it) and maybe $800 in Leanpub's advertising service (probably not worth it). Right now that doesn't come close to making back the time investment, but I think it can get there post-release. I believe there's a lot more potential customers via marketing. I think post-release 10k copies sold is within reach. Where is the book going? The main content work is rewrites: many of the chapters have not meaningfully changed since 1.0, so I am going through and rewriting them from scratch. So far four of the ten chapters have been rewritten. My (admittedly ambitious) goal is to rewrite three of them by the end of this month and another three by the end of next. I also want to do final passes on the rewritten chapters; as most of them have a few TODOs left lying around. (Also somehow in starting this newsletter and publishing it I realized that one of the chapters might be better split into two chapters, so there could well-be a tenth technique in v0.11 or v0.12!) After that, I will pass it to a copy editor while I work on improving the layout, making images, and indexing. I want to have something worthy of printing on a dead tree by 1.0. In terms of timelines, I am very roughly estimating something like this: Summer: final big changes and rewrites Early Autumn: graphic design and copy editing Late Autumn: proofing, figuring out printing stuff Winter: final ebook and initial print releases of 1.0. (If you know a service that helps get self-published books "past the finish line", I'd love to hear about it! Preferably something that works for a fee, not part of royalties.) This timeline may be disrupted by official client work, like a new TLA+ contract or a conference invitation. Needless to say, I am incredibly excited to complete this book and share the final version with you all. This is a book I wished for years ago, a book I wrote because nobody else would. It fills a critical gap in software educational material, and someday soon I'll be able to put a copy on my bookshelf. It's exhilarating and terrifying and above all, satisfying. It's also 150 pages vs 50 pages, but admittedly this is partially because I made the book smaller with a larger font. ↩

2 days ago 5 votes
Implementing UI translation in SumatraPDF, a C++ Windows application

Translating user interface of SumatraPDF SumatraPDF is the best PDF/eBook/Comic Book viewer for Windows. It’s small, fast, full of features, free and open-source. It became popular enough that it made sense to translate the UI for non-English users. Currently we support 72 languages. This article describes how I designed and implemented a translation system in SumatraPDF, a native win32 C++ Windows application. Hard things about translating the UI There are 2 hard things about translating an application code for translation system (extracting strings to translate, translate strings from English to user’s language) translating them into many languages Extracting strings to translate from source code Currently there are 381 strings in SumatraPDF subject to translation. It’s important that the system requires the least amount of effort when adding new strings to translate. Every string that needs to be translated is marked in .cpp or .h file with one of two macros: _TRA("Rename") _TRN("Open") I have a script that extracts those strings from source files. Mine is written in Go but it could just as well be Python or JavaScript. It’s a simple regex job. _TR stands for “translation”. _TRA(s) expands into const char* trans::GetTranslation(const char* str) function which returns str translated to current UI language. We auto-detect language at startup based on Windows settings and allow the user to explicitly set UI language. For English we just return the original string. If a string to be translated is e.g. a part of const char* array[], we can’t use trans::GetTranslation(). For cases like that we have _TRN() which expands to English string. We have to write code to translate it at some point. Adding new strings is therefore as simple as wrapping them in _TRA() or _TRN() macros. Translating strings into many languages Now that we’ve extracted strings to be translated, we need to translate them into 72 languages. SumatraPDF is a free, open-source program. I don’t have a budget to hire translators. I don’t have a budget, period. The only option was to get help from SumatraPDF users. It was vital to make it very easy for users to send me translations. I didn’t want to ask them, for example, to download some translation software. Design and implementation of AppTranslator web app I couldn’t find a really simple software for crowd sourcing translations so I wrote my own: https://github.com/kjk/apptranslator You can see it in action: https://www.apptranslator.org/app/SumatraPDF I designed it to be generic but I don’t think anyone else is using it. AppTranslator is simple. Per https://tools.arslexis.io/wc/: 4k lines of Go server code 451 lines of html code a single dependency: bootstrap CSS framework (the project is old) It’s simple because I don’t want to spend a lot of time writing translation software. It’s just a side project in service of the goal of translating SumatraPDF. Login is exclusively via GitHub. It doesn’t even use a database. Like in Redis, changes are stored as a series of operations in an append-only log. We keep the whole state in memory and re-create it from the log at startup. Main operation is translate a string from English to language X represented as [kOpTranslation, english string, language, translation, user who provided translation]. When user provides a translation in the web UI, we send an API call to the server which appends the translation operation to the log. Simple and reliable. Because the code is written in Go, it’s very fast and memory efficient. When running it uses mere megabytes of RAM. It can comfortably run on the smallest 256 MB VPS server. I backup the log to S3 so if the server ever fails, I can re-install the program on a new server and re-download the translations from S3. I provide RSS feed for each language so that people who provide translations can monitor for new strings to be translated. Sending strings for translation and receiving translations So I have a web app for collecting translations and a script that extracts strings to be translated from source code. How do they connect? AppTranslator has an API for submitting the current set of strings to be translated in the simplest possible format: a line for each string (I ensure there are no newlines in the string itself by escaping them with \n) API is password protected because only I can submit the strings. The server compares the strings sent with the current set and records a difference in the log. It also sends a response with translations. Again the simplest possible format: AppTranslator: SumatraPDF 651b739d7fa110911f25563c933f42b1d37590f8 :%s annotation. Ctrl+click to edit. am:%s մեկնաբանություն: Ctrl+քլիք՝ խմբագրելու համար: ar:ملاحظة %s. اضغط Ctrl للتحرير. az:Qeyd %s. Düzəliş etmək üçün Ctrl+düyməyə basın. As you can see: a string to translate is on a line starting with : is followed by translations of that strings in the format: ${lang}: ${translation} An optimization: 651b739d7fa110911f25563c933f42b1d37590f8 is a hash of this response. If I submit this hash with my request and translations didn’t change on the server, the response is empty. Implementing C++ part of translation system So now I have a text file with translation downloaded from the server. How do I get a translation in my C++ code? As with everything in SumatraPDF, I try to do things in a simple and efficient way. The whole Translation.cpp is only 239 lines of code. The core of translation system is const char* trans::GetTranslation(const char* s); function. I embed the translations in exact the same format as received from AppTranslator in the executable as data file in resources. If the UI language is English, we do nothing. trans::GetTranslation() returns its argument. When we switch the language, we load the translations from resources and build an index: an array of English strings an array of corresponding translations Both arrays use my own StrVec class optimized for storing an array of strings. To find a translation we scan the first array to find an index of the string and return translation from the second array, at the same index. Linear scan seems like it would be slow but it isn’t. Resizing dialogs I have a few dialogs defined in SumatraPDF.rc file. The problem with dialogs is that position of UI elements is fixed. A translated string will almost certainly have a different size than the English string which will mess up fixed layout. Thankfully someone wrote DialogSizer that smartly resizes dialogs and solves this problem. The evolution of a solution No AppTranslator My initial implementation was simpler. I didn’t yet have AppTranslator so I stored the strings in a text file in repository in the same format as what I described above. People would download it, make changes using a text editor and send me the file via email which I would then checkin. It worked for a while but it became worse over time. More strings, more languages created more work for me to manually manage e-mail submissions. I decided to automate the process. Code generation My first implementation of C++ side used code generation instead of embedding the text file in resources. My Go script would generate C++ source code files with static const char* [] arrays. This worked well but I decided to improve it further by making the code use the text file with translations embedded in the app. The main motivation for the change was to open a possibility of downloading latest translations from the server to fix the problem of translations not being all ready when I build the release executable. I haven’t done that yet but it’s now easier to implement given that the format of strings embedded in the exe is the same as the one I can download from AppTranslator. Only utf-8 SumatraPDF started by using both WCHAR* Unicode strings and char* utf8 strings. For that reason the translation system had to support returning translation in both WCHAR* and char* version. Over time I refactored the code to use mostly utf8 and at some point I no longer needed to support WCHAR* version. That made the code even smaller and reduced memory usage. The experience I’m happy how things turned out. AppTranslator proved to be reliable and hassle free. It runs for many years now and collected 35440 string translations from users. I automated everything so that all I need to do is to periodically re-run the script that extracts strings from source code, uploads them to AppTranslator and downloads latest translations. One problem is that translations are not always ready in time for release so I make a release and then people start translating strings added since last release. I’ve considered downloading the latest translations from the server, in addition to embedding them in an executable at the time of building the app. Would I do the same today? While AppTranslator is reliable and doesn’t require on-going work, it would be better to not have to run a server at all. The world has changed since I started SumatraPDF. Namely: people are comfortable using GitHub and you can edit files directly in GitHub UI. It’s not a great experience but it works. One option would be to generate a translation text file for each language, in this format: :first untranslated string :second untranslated string :first translated string translation of first string :second translated string translation of second string Untranslated strings are listed at the top, to make it easier to find. A link would send a translator directly to edit this file in GitHub UI. When translator saves translations, it creates a PR for me to review and merge. The roads not taken But why did you re-invent everything? You should do X instead. All other X that I know about suck. Using per-language .rc resource files Traditional way of localizing / translating Window GUI apps is to store all strings and dialog definitions in an .rc file. Each language gets its own .rc file (or files) and the program picks the right resource based on a language. This doesn’t solve the 2 hard problems: having an easy way to add strings for translations having an easy way for users to provide translations XML horror show There was a dark time when the world was under the iron grip of XML fanaticism. Everything had to be an XML file even when it was the worst possible solution for the problem. XML doesn’t solve the 2 hard problems and a string storage format is an absolute nightmare for human editing. GNU gettext There’s a C library gettext that uses .po files. This is much saner solution than XML horror show. .po files are relatively simple text format. The code is already written. Warning: tooting my own horn. My format is better. It’s easier for people to edit, it’s easier to write code to parse it. This looks like many times more than 239 lines of code. Ok, gettext probably does a bit more than my code, but clearly nothing than I need. It also doesn’t solve the 2 hard problems. I would still have to write code to extract strings from source code and build a way to allow users to translate them easily.

2 days ago 3 votes