Tools on blog.iankulin.com

Node.js built in test runner

Mon, 17 Mar 2025 00:00:00 +0000

For the longest time, I’ve been using Mocha (test runner) and Chai (assertion library) for my JS testing. They are reliable old friends.

One of the effects of the existence of Bun and Deno has been to spur Node onto adding some new features, so after appearing as an experimental feature in 18, the Node test runner dropped in Node 20.

I’m not sure if the familiar unit test layout of Mocha and Node is inherited from Jest, or comes from older testing frameworks of which JUnit and NUnit were the first ones I’d ever used. Before that I just used to write tests as lumps of assertions in regular code - which worked but wasn’t as pleasant to use as a proper unit test setup. Regardless, the system of bundling a few tests together and having them all run and spit out green ticks is not a new one.

If you are coming from Mocha, there are very few changes to your practice to make. I didn’t read the docs to check that I had to begin my test files with ’test’ or to put them into a ’test’ directory. But I discovered that dragging them into a ’test-dont’ directory didn’t stop them from running.

Testing

As well as what ever you’re testing, you need to import a couple of things from node:

import { isEven } from "../index.js";
import { describe, it } from "node:test";
import assert from "node:assert";

Then we can write our tests, grouping them in a describe:

describe("isEven", () => {
 it("returns true for even numbers", (t) => {
 assert.strictEqual(isEven(4), true);
 assert.strictEqual(isEven(0), true);
 assert.strictEqual(isEven(-2), true);
 });

 it("returns false for odd numbers", (t) => {
 assert.strictEqual(isEven(7), false);
 assert.strictEqual(isEven(-3), false);
 });

 it("returns false for most floating point numbers", (t) => {
 assert.strictEqual(isEven(3.5), false);
 // sadly, this is true because JavaScript
 // assert.strictEqual(isEven(4.0000000000000000000001), false);
 });

 it("returns false for non-numbers", (t) => {
 assert.strictEqual(isEven("a"), false);
 assert.strictEqual(isEven(null), false);
 assert.strictEqual(isEven(undefined), false);
 });
});

Then to run them, just node --test and we’ll get a nice summary

Of course there are a heap of other assertions, as well as stuff to set-up and tear-down and to mock things such as times. What I’ve shown here is very much a getting started, but it also deals with about 80% of my testing needs.

I’m not entirely sure how I feel about moving to a built in test runner. The small convenience I gain has to be weighed up against a small amount of lock in to a run time. I haven’t yet been tempted to Deno or Bun, but I love that they exist and are spurring on innovation. Possibly I’ll continue with portable testing tools for big projects, but for little ones use the built in.

Testing Node.js apps - Mocha, Chai, and Supertest

Mon, 01 Jan 2024 00:00:00 +0000

Bruno is a great open source Postman/Insomnia replacement, and I’ve been using it for basic tests of my node servers using the built in asserts and loving it. This is pretty great, and I gather it’s also possible to go beyond this and write tests in JS in Bruno. I believe it also has the hooks needed to build it into your CI/CD systems.

Any large project is probably going to benefit from a more comprehensive suit of testing tools, and while I’ll still be using Bruno, my serious tests will be managed with these other tools.

I admit I’ve probably put this off a bit longer than I should have - I didn’t really want to install four dependencies and learn four different things just to test my endpoints. It turns out that using the tools together is seamless, and setting it all up was trivial.

Speaking of trivial, here’s my brilliant Node app. It has two endpoints, both of which do a bit of maths.

const express = require('express');const app = express();const port = 3000;app.use(express.json());// endpoint that takes two numbers and returns their sumapp.post('/sum', (req, res) => { const { a, b } = req.body; res.json({ sum: a + b });});// endpoint that takes two numbers and multiplies themapp.post('/multiply', (req, res) => { const { a, b } = req.body; res.json({ product: a * b });});// start the serverapp.listen(port, () => { console.log(`Maths server is running at http://localhost:${port}`);});

Setting up your project for testing

Install the tools

npm install --save-dev mocha chai supertest

The --save-dev bit installs them as a development dependencies - they will go in your package.json and everyone who clones the repo will be working with the same version. Additionally, they won’t needlessly be installed when deployed to production.

Export the app

The testing system needs to be able to control the app a little bit - start it, stop it, and hook into it. To do that, we’ll complicate our app.listen code a bit so that we’ve also got a server variable, then we’ll export the app and server so out test files can import them. It will end up looking something like this:

let server;if (process.env.NODE_ENV !== 'test') { server = app.listen(3000, () => console.log(`Maths server is running at http://localhost:${port}`));}module.exports = { app, server };

This stops the server being started here if we’re in test mode, but exports the bits the test framework needs to manage things.

Create the test files

Our JS test code is all going in a test/ directory in our project, and they will all be named <something>.test.js I usually use the file name of the file I’m testing. So today I’m writing tests for app.js my tests will be in apps.test.js

Each test file will need to pull in our tools (supertest and chai) and the server and app variables.

That’s followed by one or more test suites; each test suite contains one or more test cases. This might be easier to explain if we look at a real file:

const supertest = require('supertest');const chai = require('chai');const { app, server } = require('../app');const expect = chai.expect;describe('POST / add', () => { it('should return the correct sum', () => { return supertest(app) .post('/sum') .send({ a: 5, b: 5 }) .expect(200) .then(res => { expect(res.body.sum).to.equal(10); }); }); it('should return the correct sum with negative numbers', () => { return supertest(app) .post('/sum') .send({ a: -5, b: -5 }) .expect(200) .then(res => { expect(res.body.sum).to.equal(-10); }); });});describe('POST / multiply', () => { it('should return the correct product', () => { return supertest(app) .post('/multiply') .send({ a: 5, b: 5 }) .expect(200) .then(res => { expect(res.body.product).to.equal(25); }); });});server.close();

This file contains two test suites - ‘POST/add’ and ‘POST/multiply’. POST/add contains two test cases (each begins with it<statement of what the test subject should do>).

There’s no end to the tests you can write. I normally do basic functionality as I’m writing code, and I also add in tests for anything that emerges as a bug. If you get into the rhythm of bug -> write failing test -> fix bug -> test passes you can have your day punctuated by little doses of dopamine. I often write a timed test - that an endpoint should respond in 10ms. These don’t help you when you are developing, but sure will later. You should also check that all of the wrong inputs users will eventually try have been handled. If an API expects a number, check for errors being thrown for strings, for negative numbers, for huge numbers, for decimals, for booleans, for objects etc etc.

Another thing I will do is use a code coverage tool to check my test covers all the branches and error conditions. I plan to talk about that another day. First I need to show you how to run the tests.

Add test script

If we had installed mocha globally, we could just call it from the command line with something like:

mocha ./test/app.test.js

But we didn’t do that, so we need npm to start it up for us. I know this seems like another time wasting step, but it’s one of those do it once, benefit from it thousands of times things.

In the package.json file, we can add a section called scripts. If you started you project with npm init you may already have this section, if not, just add it in. It’s common to have a run and a test script, and I often have one or two others. Here’s the sort of thing you want.

{ "name": "test-demo", "version": "0.1.0", "description": "Simple Maths API", "main": "app.js", "scripts": { "start": "node app.js", "test": "mocha './test/*.test.js'" }, "dependencies": { "express": "^4.18.2" }, "devDependencies": { "chai": "^4.3.10", "mocha": "^10.2.0", "nyc": "^15.1.0", "supertest": "^6.3.3" }}

npm does the magic to make the correct version of the library available when this script is run. The end effect of these is that you can type npm test at the command line, and mocha will run your tests. Let’s try it would our tests.

That’s what we like to see, passing tests. I’ll make one fail by telling it to expect 5x5=26.

And that’s it, you’re all set up to write tests against your node apps.

What do the different bits do?

There’s a lot of moving parts here, lets tease those out a little.

mocha - this is the test framework. As we’ve discussed, it’s the command line tool that runs the tests and produces the output.

supertest - manages the connections between the test runner/framework and the code being tested. When I’m pressing a button in Bruno, it’s actually hitting localhost:3000 to exercise the server which I’ve previously started. supertest is doing magic to make that connection without going through the network layers.

chai - it provides the assert()s, expect()s and should()s that we use in the test cases. You could, in theory make do with the assert() library built into node - especially for our toy demo app - but it’s no where near as nice, and in particular chai has a massive set of plugins that both extend it’s use generally, but also into working at a detailed level with other vendor packages.

Bruno asserts

Sat, 11 Nov 2023 00:00:00 +0000

I mentioned Bruno the other day. Although it’s still very much under development, it is shaping up as a great Postman/Insomnia replacement.

One of the aspects I’ve been using today is asserts. As part of a request, you can add some asserts - so when you’re hitting an endpoint it will check what status should it be returning, or given the data you’re passing in, what should be in the response body.

When I’d asked ChatGPT to to review the mdserver code, it had suggested that I should be sanitising URL inputs better to prevent users transversing out of the ‘public’ file directory to other places in the file system. I thought Express had already taken care of this for me, but wanted to check. I had ChatGPT generate a bunch of pass and fail URL examples, then just created asserts for each one in Bruno.

Once that’s done, you can just right click on the collection and have it run all of those.

An extra benefit of Bruno is that all these requests are stored as JSON-like, version-controllable text. I store them in my project and commit them along with the rest of my code.

We need to talk about Bruno

Fri, 27 Oct 2023 00:00:00 +0000

I’ve mentioned before that I was using Insomnia as a tool to check my REST APIs as I was developing them, and that I was avoiding Postman (which I guess is more widely used since it’s worth USD5.6 billion) because

The only reason I’m using Insomnia instead of Postman is that when I tried Postman, it straight away wanted some of my data to make it work. Insomnia hasn’t forced me to do that yet.

Sadly that was prophetic. I saw @wtpisaac@vmst.io mention this exact thing had happened.

The following day when I opened up Insomnia, it asked to upgrade and I said no, and was able to write and save a handful of new calls to test the API I was building. Sadly, I closed it, and of course on the next run, it demanded an account be created. I skipped that, and it presented me with a “sandbox” and all my saved requests were gone.

Luckily, Isaac also suggests a solution - Bruno. This is a 1K star FOSS project by helloanoop. There are Mac, Windows and Linux clients, as well as a CLI and VSCode plugins. One of it’s selling points (apart from it’s not Postman or Insomnia) is that the collections of requests are saved in very simple human readable text (a language called bru) so it’s straightforward and sensible to commit them to source control along with your code.

This video from Anoop (with a very clickbait-y title) does a good job of explaining his project.

I’ve only played around with Bruno for an afternoon, but I’m loving it so far. Seems like it will do everything I need, and the diffable files for the requests are a bonus. This is a project that deserves to be better known.

Hide 'Problems' for a file in VS Code

Fri, 25 Aug 2023 00:00:00 +0000

I’m interested in trying out Pico CSS - a lightweight CSS library, but when I tossed it into my project, the linter found and reported 29 problems. One of my processes is to just keep that problems tab clear as I work, so I’d like that to go away.

It’s possible, but only by ’excluding’ the file from your project - it won’t show up in the file view either. That’s fine with me, I never want to deal with the file so we’ll do that, although it might confuse me in seven years if I come back to this project, so I’ll drop a link in my .git_ignore as a clue for future me (excluding the file in VS Code doesn’t affect git finding it).

Workspace settings (such as excluding a file) are stored in ./vscode/settings.json - this has some other bits and pieces such as spelling corrections etc. It’s worth letting this into your repository so your workspace is recreated when you clone the repo. The fragment you need to add is:

 "files.exclude": {
 "**/pico.min.css": true
 }

This will remove it from the files, and it will stop it being processed by your extensions including any linters. If the problems don’t disappear instantly, click into a different file for a second and they should go, or occasionally, you’ll need to close and open VSCode.

CodePen

Sun, 29 Jan 2023 00:00:00 +0000

I think I’ve written about CodePen before, its a site that allows users to quickly put together HTML, CSS & JS and see the results as they edit. Users ‘pens’ are public and can be tagged, so it also serves as a repository of examples.

It’s possible to host incredibly complex artefacts, such as this 3D Sony Walkman, but what I mostly use it for is to work out simple things - like how to collapse a row of text into a column with a media query.

The alternative to a site like this for those jobs would be to create a couple of scratch files and open up another instance of VS Code, but this is quicker, the results are immediately available, and are saved if I ever need to go back to them.

The free tier more than covers my needs, but the paid tier (about $10 a month) includes being able to make your pens private and hosting image assets there. The private options would be nice to hide your tests if you were going to use it as a portfolio - which I don’t doubt some designers would.

As a bonus, pens can easily be embedded in blog posts on WordPress.

View embed

Digital Color Meter

Wed, 18 Jan 2023 00:00:00 +0000

For the Calculator project, I needed to know the exact RGB values for the colours on the iOS calculator buttons so I could reproduce them. Assuming a tool for reading colours from the screen exisited, I googled it, and was surprised to find this exact tool is already installed by default on MacOS.

It’s called Digital Color Meter and just shows the RGB values for anything on the screen under the cursor.

In order to copy the values, hit Command|L to freeze the current colour, then copy them from the Colour menu. Also in that menu you can choose to have the values shown as hex.

Cursor in screenshots

While I’m doing tips and tricks, to have the cursor showing in a Mac screenshot (which I needed for the image above), do shift|command|5 (which is the time delay whole screenshot) then turn it on in the option bar that appears before starting the timer.

Lost in Translation

Wed, 11 Jan 2023 00:00:00 +0000

We’re in a pretty good place now (compared to a few years ago) in terms of being able to rely on JavaScript behaving the same on different platforms. There’s still some differences (mostly in when things are implemented) but overall, not to bad once you decide to no longer support Internet Explorer.

In times past, it was a lot more painful. A few of approaches to deal with this arose. One is to let a library, such as jQuery or a polyfill deal with it, and the other is use a translation utility such as Babel to down convert (transpile) your modern JavaScript to something that will run in more browsers.

Babel can be run from the command line, and therefore integrated into a toolchain, but if you want to have a play with it, they have an interactive version on their web site. Here’s a couple of examples of how arrow functions and backtick templates get converted to run on IE 6.

CodePen.io

Thu, 05 Jan 2023 00:00:00 +0000

I quite often leave a link to a GitHub repo to share my source in these posts, and on a few recent ones, a link to a live version of a page on my github.io. In a recent installment of CWD, Andrei shared some previous students’ solutions, and some were hosted on CodePen.io which I hadn’t seen before.

It’s a cute concept, you can enter HTML, CSS & JS and see a live view of the page below. It looks super extensible - there’s mentions of SCSS, Typescript and preprocessors for JS in the settings.

There are a few quirks - you don’t enter all the DOCTYPE/ etc in your HTML- presumably that’s because they already need that for their page. There are settings for some of these for example if you need to add a clss to the . I couldn’t see how to do that for the though so I needed to change the JS for this project a bit.

It seems pretty great - sort of like Playgrounds for web dev. It’s not quite a full debugging IDE - that doesn’t seem to exist for web dev. There’s no intellisense, but it was flagging problems in my JavaScript, so I’ll use it for a few of these tutorial pages and see how it goes.

Here’s a link to the tutorial app above on CodePen.

Running Javascript in VS Code

Tue, 27 Dec 2022 00:00:00 +0000

I’ve been using the Live Server plugin to see HTML & CSS updated as I edit, and that will also be useful when I start using Javascript for web development, but as you can see above, I’m not quite up to that. It seemed there should be a way to run JS in VS Code, and it turns out it’s easy.

You just need something installed that can run Javascript. Node.js is the obvious choice, and you’re going to need it later in your development journey. Just install Node.js then the first time you try to run some JS in VS code, it will ask you what to use, select Node and you’re in business.

I found out about this from here. I didn’t worry about Code Runner - just using Node.js worked for me without any fiddling beyond installing it (this is on Mac though - your Windows mileage may vary).

While I’m doing handy hints for dev tools, I discovered last night that the baby webserver that Live Server is running, isn’t just available on the local machine, it’s available to anyone on your network. Instead of using 127.0.0.1:5500, use the IP address of your development machine (but still port 5500 if that’s what you’re using). It’s an excellent way to look at your layout on phones etc, or, I guess, to see what other devs at your company are working on :- )

Who is Emmet?

Wed, 14 Dec 2022 00:00:00 +0000

I knew there was some magical way of entering all the the boilerplate in Visual Studio Code as I’d seen it happen in several videos, and assumed is was some sort of macro expansion thing in the editor. Fast forward a few blog post readings and youtube viewings and I keep seeing tangential references to someone called Emmet. Turns out they’re the same thing, and it’s pretty cool.

It’s not a new idea to have functionality in code editors to insert snippets of code. Emmet goes a bit further than that - and like many tools made by programmers for programmers it goes way to technical to the point where you need to memorise ridiculous amounts of combos to to some awesome stuff (I’m looking at you whoever made it possible to use vi commands in VS Code). Nevertheless, Emmet is extremely handy even at my n00b level.

The key thing to know, is that it borrows from the CSS selector syntax. So if you want to insert <div></div> you enter div and press tab.

Want a div with a class named “container”?

div.container becomes <div class="container"></div>.

The same trick works for an id - Enter

div#emmet becomes <div id="emmet"></div>

Would you like a div, with a heading inside? The greater than sign nests elements, so div>h4 becomes:

<div>
 <h4></h4>
<div>

If you’d like some text up in there, try div>h4{Hello world}

<div>
 <h4>Hello world</h4>
</div>

You can repeat things numbers of times, so to create a list with three items, try ul>li*3 to get:

<ul>
 <li></li>
 <li></li>
 <li></li>
</ul>

That’s about as complex as I’d want to get, though of course it gets more complex. It’s a super handy feature that quickly becomes second nature.

ChatGPT's code writing

Sun, 11 Dec 2022 00:00:00 +0000

This week, the internet has been all about ChatGPT, the rather remarkable natural language AI with a very large model. If you’re a twitter user, you were probably amazed, but now eventually tired of seeing examples of it’s output. I’ll add to that with an example of a SwifUI CoreData based todo app it wrote for me from a single sentence prompt below. Rather than look at other people’s examples you should definitely go and play with it yourself - it is very impressive. Along with the image based AI’s it’s made 2022 into a historical year for AI.

ChatGPT will write software. I can’t see it replacing developers, but it seems likely there’ll be a bunch of interesting tools to come over the next few years. I feel like the first big effect will be the volume of mediocre internet content will increase dramatically as it is pretty great at run of the mill copy-writing. I’d like to assure my readers that all my mediocre internet content will continue to be human written - with the exception of most of the art, and the code example below :- )

write swiftui code for a todo application where the items reoccur after a certain number of days. The items are shown in a list and the user can navigate to a detail view.

me

Here is an example of SwiftUI code for a todo application where the items reoccur after a certain number of days:

ChatGPT

struct TodoItem: Identifiable {
 let id = UUID()
 let task: String
 let dueDate: Date
 let repeatInterval: Int // number of days until the task reoccurs
}

struct TodoList: View {
 @State var items = [TodoItem]()

 var body: some View {
 List(items) { item in
 NavigationLink(destination: TodoDetail(item: item)) {
 Text(item.task)
 }
 }
 }
}

struct TodoDetail: View {
 let item: TodoItem

 var body: some View {
 VStack {
 Text(item.task)
 Text("Due: \(item.dueDate, formatter: DateFormatter.mediumDate)")
 Text("Reoccurs every: \(item.repeatInterval) days")
 }
 }
}

In the TodoList view, a List is used to display the todo items. Each item in the list is wrapped in a NavigationLink that takes the user to a TodoDetail view when tapped. The TodoDetail view displays the task, the due date, and the repeat interval for the selected todo item.

You can modify this code to suit your specific needs, such as adding features to add or delete items, or changing the layout and appearance of the views.

ChatGPT

That’s pretty cool. I don’t think that DateFormatter.mediumDate is a thing, so I changed that line to:

Text("Due: \(item.dueDate, style: .date)")

It’s okay ChatGPT, I get confused about the variety of ways to change dates too.

great. show me the content view code that contains the TodoList and has a button to add items.

me

Here is an example of a ContentView that contains a TodoList and has a button to add items:

ChatGPT

struct ContentView: View {
 @State var items = [TodoItem]()

 var body: some View {
 VStack {
 TodoList(items: $items)
 Button(action: {
 // add new todo item here
 }) {
 Text("Add Item")
 }
 }
 }
}

In this code, the ContentView contains a TodoList and a Button. The TodoList is initialized with the items array, which is marked as @State so that it can be modified in response to user actions. The Button has an action closure that is executed when the button is tapped. You can add code inside this closure to create a new TodoItem and add it to the items array.

You can modify this code to suit your specific needs, such as changing the layout and appearance of the views, or adding features to delete items from the list.

ChatGPT

To let this compile, I commented out the Preview and changed the items property in the top of the TodoList view to a binding:

struct TodoList: View {
 @Binding var items: [TodoItem]

thank you. what would the code for adding an item look like

me

Here is an example of code that you can use to add a new TodoItem to the items array when the button is tapped:

ChatGPT

struct ContentView: View {
 @State var items = [TodoItem]()

 var body: some View {
 VStack {
 TodoList(items: $items)
 Button(action: {
 let newItem = TodoItem(task: "New Task", dueDate: Date(), repeatInterval: 7)
 items.append(newItem)
 }) {
 Text("Add Item")
 }
 }
 }
}

In this code, the Button has an action closure that creates a new TodoItem with the task “New Task”, a due date of the current date, and a repeat interval of 7 days. The new item is then appended to the items array.

You can modify this code to suit your specific needs, such as prompting the user for the task name and due date, or changing the default repeat interval. You can also add additional logic to handle errors or validation failures when creating the new item.

ChateGPT

This all runs and the add item works, but the NavigationLink to get to the detail view does not. Let’s wrap it in a NavigationView to fix that.

struct ContentView: View {
 @State var items = [TodoItem]()

 var body: some View {
 NavigationView {
 VStack {
 TodoList(items: $items)
 Button(action: {
 let newItem = TodoItem(task: "New Task", dueDate: Date(), repeatInterval: 7)
 items.append(newItem)
 }) {
 Text("Add Item")
 }
 }
 }
 }
}

I went on to ask it to change this to core data for persistence, but as I wanted the app to be more and more complex, it needed me to fix more and more problems, and became less fun.

Copying a file via SSH

Tue, 29 Nov 2022 00:00:00 +0000

I have a Raspberry Pi on my home network that I purchased for some project that I can’t actually recall. It gets used for all sorts of completely unnecessary things such as playing with node.js or a private git server. To add to the list of things that I do on pi that could be more efficiently done on my MacBook I wanted to host my sample JSON from yesterday on it.

I’d already downloaded the JSON to my laptop (although I could have skipped that step and used curl to download it directly to the pi) and just wanted to transfer it into the apache html directory.

I feel like in 2022 I should just be able to SSH to the directory on the pi, then drag and drop the file from my mac, but that’s not possible (although it does usefully paste the filepath to the file which could be helpful). Of course there is a command for this, you just need to know it - scp

My pi is on 192.168.100.13 and I log in as ian. The file I want to copy is called sample_students.json.

In a terminal window, on your development machine:

scp sample_students.json ian@192.168.100.13:/home/ian

The first argument is the file to copy, and the second is the ssh accessible machine you are copying to with the path after the colon.

Mock Data

Mon, 28 Nov 2022 00:00:00 +0000

One of the things we need during app development is some data to play with. It would be unethical for me to use real student data to test my app, even if I wasn’t sharing screenshots of the development here, so I’ll need to build some mock data. The prospect of making 400 rows of data manually does not sound like a good use of time, so I started to think about generating it in Excel. I’d used an online “random address generator” for an earlier project, so I was contemplating pasting that sort of data into Excel workbooks and randomly selecting from it.

It occurred to me someone probably already solved this problem, and a quick search confirmed there are hundreds of web based test data generating sites. They provide data in all sorts of formats as downloads or via APIs. Somewhat at random, I selected Mockaroo.

In addition to letting you specify the fields, you control the type of data to go in them. They have a heap of options of specific formats such as ISBN’s, airport codes and so on. The whole thing took a couple of minutes to setup.

As I was doing it, it occurred to me that a completely random date of birth didn’t make perfect sense - there really should be a connection between the year group of students and their date of birth. It’s completely immaterial for this project, so I didn’t bother with it, but in fact Mockaroo has ruby based scripting that allows you the flexibility to make one field somehow calculated from others so that would be possible

It was a simple matter to download my data as JSON, but there’s also options for fetching it from a REST API.

I’ll download and host this on my home Raspberry Pi server that I bought for a different project, but it’s possible just to pull it direct from their server.

A small note of caution is that if you sign in to save your schema, it is saved, but it’s also public. That may not matter for your context, but in some situations it could be important. This could be from the data you provide as options, or even just the property names might provide intelligence useful to someone. As IT professionals we need to be mindful of the risks we’re taking with client or user information and to either eliminate or explain them.

iOS 16 Developer Mode

Sat, 19 Nov 2022 00:00:00 +0000

I updated my iPhone to iOS16 this morning, and tonight when I went to run one of my apps, it complained that it needed Developer mode. This is a new, probably wise, way to avoid dodgy apps being loaded on a phone. I don’t know exactly how you’d do that, but then I’m not a black hatted cyber terrorist.

I had to google the setting, it’s in “Privacy and Security” down the bottom, and requires a reboot. When you open the phone there’s another dialog and you need to reauth.

SwiftLint

Mon, 10 Oct 2022 00:00:00 +0000

I was watching a Tim Ruscica video about the things that highly effective developers do, and it called to mind a book I read years ago called Code Complete. It is the only book I ever owned that I immediately purchased the new edition when it came out. It was about the meta stuff around programming that is the difference between coding and developing. In particular, it got me invested in source control and testing.

If you’ve been reading along, you’ll know I am keen to leverage the great tools available to support quality software development, and one I haven’t tackled till this week is a linter.

Linters are tools to enforce (or at least suggest) rules to improve your code that are not strictly necessary (the compiler hasn’t enforced them) but they make your code better, or at least prettier, in other ways. I gather the most popular linter for Swift is SwiftLint.

I installed it by downloading and running the .pkg. Then in any Xcode projects you want to use it in, you go into Build Phases for the current Scheme in your project and add a new script that runs SwiftLint on the files in the project’s folder. There’s a good step by step here by Vineet Choudhary. You should end up with something like this:

Now when you Command-B to build your project, the linter will run and (especially the first time) add some extra warnings and errors.

SwiftLint has many rules. Some are default rules (these are the most widely accepted ones) and some are optional. Turning rules off or on, or altering their parameters is done using a swiftlint.yml config file in the top level folder of your project.

Here’s an example from mine, where I want to alter a rule:

vertical_whitespace:
 max_empty_lines: 2

There’s a rule called vertical_whitespace. It throws a warning if there is more than one consecutive empty line in a file. I use two line gaps all over my code to signify a separate method or function, so that does not work for me. The config change above changes it to allow two empty lines. This same config file can also be used to disable any of the default rules, or enable any of the optional rules.

Rules can also be disabled and enabled in your code with special comments. For example, in my tests, I have enormous multi-line strings which don’t follow proper indentation for a deliberate reason, so at the top of this file I have:

// swiftlint:disable line_length
// swiftlint:disable indentation_width

You can turn rules back on as well. For example in this code snippet I have code that the linter wants me to write as a trailing closure, but I’m not sure how to do that in this situation yet - so I turn the rule off before it, then back on.

func stripSpaces(_ codeLines: String ) -> String {
 // break into lines
 var lines = codeLines.components(separatedBy: "\n")
 var minCount = Int.max
 // step though the lines and count how many spaces, save the minimum amount
 for line in lines {
 // swiftlint:disable trailing_closure
 let leadingSpaces = line.prefix(while: { $0 == " " }).count
 // swiftlint:enable trailing_closure
 minCount = leadingSpaces < minCount ? leadingSpaces : minCount
 }
 // step though the lines again, and trim the min amount from each line
 for index in 0..<lines.count {
 lines[index] = String(lines[index].dropFirst(minCount))
 }
 // stitch it back up
 return lines.joined(separator: "\n")
}

My strategy with the linter was to turn all the optional rules on, then run it and go through to consider each of the optional rules I’ve transgressed to decide if it makes more sense to me to change the code or eliminate the rule.

Testing, testing

Sun, 09 Oct 2022 00:00:00 +0000

I have unit testing in my goals, and if I’m going to throw this space trimming macOS utility up on the web, now might be a good time to figure out how to add unit tests to a project, how to write them, and how to run them. XCode is well set up for this, so it’s really no drama to do.

Although I haven’t worried with any unit testing up to this point in my iOS/Swift learning, in my previous programming work I did a lot of work with the large calculations involved in translating GPS coordinates and robotic positioning models where errors would be bad - so I’ve written a lot of tests over the years. I’ve also definitely felt the confidence you can dramatically refactor code with when you know the code has a robust test suite. I’m a big fan.

Adding Tests to Existing Project

In Xcode, with your project open, you need to add the testing target. File | New | Target... then scroll down to find the Unit Testing Bundle. When you add that, you’ll see a new folder in the Project Navigator, and a new source file - both with the name <app name>Tests.

If you click into the <app name>Test.swift file, you’ll see a couple of methods for setting up the testing environment and cleaning up after it. They are called before and after each test - you’d use them if you needed to set something up like some files in a directory or similar and wanted to ensure it was not affected by the tests run before the current test. Don’t worry about them for the time being.

Writing Tests

Before we can write any tests, we need to import any modules with the code we want to test. In my case, I want to test the function stripSpaces() which is in the ContentView of my app called CodeTrimmer. So in the top of the CodeTrimmerTests.swift file, under the other import, I add the import:

import XCTest
@testable import CodeTrimmer

Then we can write our tests. The test functions must start with the magic prefix test so that Xcode treats them as such. The usual approach in the test is to call a function with some specific input, then test the output is what is expected with a special test version of assert():

Here’s a couple. My function stripSpaces() deletes a number of spaces from each line of a block of code such that the block becomes left aligned. if the XCTAsserts() pass, the test passes and I get a green tick. To run the tests I just click in the breakpoint gutter next to the function declaration.

 func testStripSpaces01() throws {
 let testString =
 """
 single line string no spaces
 """
 let resultString = stripSpaces(testString)
 XCTAssertTrue(resultString == testString, testString)
 }

 func testStripSpaces02() throws {
 let testString =
 """
 single line 4 spaces
 """
 let resultString = stripSpaces(testString)
 XCTAssertFalse(resultString == testString, testString)
 XCTAssertTrue(testString.dropFirst(4) == resultString, testString)
 }

How to upgrade XCode and Swift

Sun, 18 Sep 2022 00:00:00 +0000

With the September release of XCode 14 and Swift 5.7 it was time for my first update - I looked in “About” for an update link but there wasn’t one - so if you’re as dense as me, the tip is to head to the Mac App Store and have a look at the Updates page.

Your current XCode version can, of course be found in the XCode | About dialogue. Mine was on 13.4.1. There’s a couple of ways of finding the Swift version - If you’ve got an XCode project open, click on the .xcodeproj in the explorer,and have a look in Build Settings for Swift Compiler - Language for the major version.

Or for a bit more accuracy, try xcrun swift -version at the command line. I got a few errors, then the version 5.6.1

I won’t bang on about the changes for XCode or Swift since that’s already been done well elsewhere, and the Swift changes are mostly beyond my expertise level.

Visual Studio Code

Fri, 19 Aug 2022 00:00:00 +0000

I’ve noticed Visual Studio Code in a few videos, and admired what a clean interface it had, and was impressed how opening a terminal window was automatically in the directory you were working in.

I had a need to write some html/css, and some C++ in the last couple of days, so that seemed like a great excuse to give it a try. I’d have to say my opinion of it has only gone up. Clearly, it is right at home with HTML and CSS - code completion and syntax colouring all working nicely. I followed TechWithTim’s suggestion to install the Live Server extension - which was a completely painless experience.

Same positive experience when I created a .cpp file, and VSC wanted me to take Microsoft’s advice about a bunch of extensions, and correctly suggested I build with Mac’s clang compiler.

So many things just work how you expect them to. Within seconds I was trying out breakpoints, compiling and managing the git commits. I even tried the Swift extension.

I have no intention of leaving Xcode, but with a great tool like this, I will never be a vim guy.

Oh My Zsh

Sat, 06 Aug 2022 00:00:00 +0000

I’ve been playing in the zsh shell since I started on the Missing Semester, and was wondering how to get my git branch name in the prompt. A few googles later, I’ve installed Oh My Zsh, and added the git and macos plugins. Pretty.