DEV Community: Karl Stolley

Properly Configuring Nightwatch to Run Geckodriver

Karl Stolley — Sat, 26 Mar 2022 22:05:55 +0000

I’ll get right to it: both the stock Nightwatch configuration file (as of at least Nightwatch v. 2.0.9) and the Nightwatch docs are inaccurate for using the geckodriver web driver (specifically, v. 0.30.0) to run tests. Here is what you need to do, isolated to the firefox environment portion of the test_settings object in a nightwatch.conf.js file:

module.exports = {

  // snip, snip, snippety-snip

  test_settings: {

    // more snipping...

    firefox: {
      capabilities : {
        browserName : 'firefox',
        acceptInsecureCerts: true,
        'moz:firefoxOptions': {
          args: [
            // '-headless',
            // '-verbose'
          ],
          prefs: {
            // 'media.navigator.permission.disable': true,
            // 'media.navigator.streams.fake': true
          }
        }
      },
      webdriver: {
        start_process: true,
        server_path: '',
        host: '127.0.0.1',
        port: 4444,
        cli_args: [
          // very verbose geckodriver logs
          // '-vv'
        ]
      }
    }

  }

};

Curious about what’s going on? I’ll elaborate, property by significant property:

The property you want is capabilities, not desiredCapabilities. The capabilities property is what ultimately shipped in the WebDriver specification. While it seems that both geckodriver and chromedriver continue to support the older desiredCapabilities, capabilities is the property you want now and into the future.
The acceptInsecureCerts property should be a member directly on capabilities; this too is in the WebDriver spec. And in testing today, it seems that some combo of Nightwatch and geckodriver ignore acceptInsecureCerts in any other location.
For Firefox-specific options (like command-line args and browser about:config prefs), the property to use is moz:firefoxOptions. That is shipping in the latest default nightwatch.conf.js file, as is the parallel goog:chromeOptions for chromedriver. But if you've got a legacy configuration file—like I did—you'll want to update the old chromeOptions property, too.
For local testing, you’ll want to set an IPv4 address to your local loopback for the host property on webdriver. On the Macs I was working on (one Big Sur, one Monterey), localhost was resolving to the IPv6 ::1 adddress. Geckodriver was refusing the connection on that, as I discovered by running wget out of desperation. wget then retried on 127.0.0.1:

  $ geckodriver
  1648330755779 geckodriver INFO    Listening on 127.0.0.1:4444
  # separate terminal process, with geckodriver still running:
  $ wget http://localhost:4444/
  --2022-03-26 16:49:18--  http://localhost:4444/
  Resolving localhost (localhost)... ::1, 127.0.0.1
  Connecting to localhost (localhost)|::1|:4444... failed: Connection refused.
  Connecting to localhost (localhost)|127.0.0.1|:4444... connected.
  HTTP request sent, awaiting response... 405 Method Not Allowed
  2022-03-26 16:49:18 ERROR 405: Method Not Allowed.

The 405 error is expected: there's no meaningful resource on the geckodriver for GET /. But the Nightwatch test-runner (I assume) did not attempt such a retry. Instead, it left behind a seemingly impossible error message of Failed to connect to GeckoDriver on 127.0.0.1 with port 4444.

Bonus information: geckodriver now supports parallel testing, where two browsers can be open once! This is important for me, as I’m using Nightwatch to test out the code I’ve been writing for my book on WebRTC. I’ll save the full instructions for how to pull off parallel tests in full for another post, but essentially, you just need two different environments (I have firefoxActive and firefoxPassive, rather than just firefox). And each environment must have its own webdriver process on its own port. So 4444 (the default) on one, and say 4445 on another. When you go to run nightwatch, pass in the -e argument with the two environments: npx nightwatch -e firefoxActive,firefoxPassive.

WebRTC Book Update: Revised TOC and Some More Legroom

Karl Stolley — Mon, 31 May 2021 16:08:19 +0000

It’s the end of May, and I’m now about ten weeks into the contracted part of this project for Pragmatic Programmers. And in the last week, the book has grown from its original proposed 6 chapters at 150 pages to 8 chapters that will weigh in at around 250 pages. That gives me a lot more room to work and should prevent anything vital from having to be cut.

As I put the finishing touches this week on the work for my first major milestone—the three-chapter publisher’s review, which I’d originally planned for mid-June—the table of contents its looking like this, minus an introductory setup chapter that’ll be part of the frontmatter and an appendix showing a signaling channel written in pure WebSockets (the book itself uses Socket.IO in its recently released version 4):

Working with a Signaling Channel. Readers set up an interface in HTML, CSS, and JavaScript to manage a basic video-chat app and wire up a pre-built signaling channel and its callbacks. A high-level description of WebRTC contextualizes the signaling channel’s purpose and limited features.
Establishing a Peer-to-Peer Connection. Picking up right where the last chapter left off, readers learn to request permissions for camera/mic access and display the resulting stream. They then go on to create a peer connection using the “perfect negotiation” pattern described in the WebRTC specification and build out the rest of the basic video-chat app.
Handling Data Channels. Media streaming is WebRTC’s most famous feature, but it’s data channels that really open up the possibilities for all kinds of real-time, peer-to-peer apps. Readers add a video-filter function to the app built over the first two chapters and then build a complete text-chat feature.
Streaming Complex Data. Data channels can handle more than simple strings. This chapter opens with building fallbacks into the perfect-negotiation code so they can more confidently test their work, including especially with data channels, on browsers that have poorer implementations of WebRTC (ahem, Safari). Readers work with sending and receiving JSON strings to build out the chat feature further, and then turn to streaming binary data—as either Blobs or ArrayBuffers, using some clever feature-detection—to share images in the chat. Readers build a standalone peer-to-peer file-sharing app to close out the chapter.
Building Peer-to-Peer Interfaces. The first four chapters cover all the fundamentals of WebRTC. This chapter looks more closely at real-time, peer-to-peer interface design—all framed by accessibility. Readers learn to build interfaces that take advantage of semantic HTML and ARIA attributes, while also giving users greater control over real-time interfaces, such as arranging interface elements in relation to their cameras.
Managing Multi-Peer Connections. This chapter moves from one-to-one to many-to-many WebRTC apps. Sticking to the browser-based focus of the book, it introduces a mesh-network architecture for connecting three or more peers in a single call. Readers also learn the practical and theoretical upper limits to the number of simultaneous peer connections, and begin to work with the RTCPeerConnection.getStats() interface.
Optimizing Media Streaming. Readers take a deep dive on different media APIs in this chapter, and learn to optimize streaming media based on local and remote statistics and even the simple appearance of media streams in the browser (how big does that video stream need to be? how small can it get?). The chapter also looks at current and forthcoming methods for optimizing images sent over data channels, including the exciting but currently not universally supported self.createImageBitmap() method.
Deploying WebRTC Apps to Production. This final chapter of the book looks at what it takes to deploy a WebRTC app into production. Readers learn about using public STUN servers as well as setting up a private STUN/TURN server, with the TURN component as a fallback for when a direct peer-to-peer connection cannot be established.

There are a lot of topics packed into chapters six, seven, and eight especially. So I wouldn’t be surprised to discover a topic that deserves its own chapter—either on my own as I write or from feedback that’ll come in from the technical and beta reviews later in the summer.

The first three chapters are draft complete, apart from some intro and outro work that I need to do today. And I’ve got good chunks of the fourth and sixth chapters coming along, in addition to a growing number of topics for the fifth chapter, on interfaces and accessibility.

Put another way, this is starting to feel more like a book to me—and not just a collection of stuff I’ve written. Considering that the spring semester just ended for me a little over two weeks ago, I’m pretty happy with where I am. But I’m hoping to pick up the pace as I recover from this weird academic year and settle into the summer.

Working to Get Off the Sidelines

Karl Stolley — Tue, 18 May 2021 20:48:00 +0000

For the last few weeks, the brisk progress I’d been making on my WebRTC book basically ground to a halt thanks to my “day job” (as my development editor whimsically puts it). My day job is being a professor, and there’s really no worse time of year than mid-April until final grades get turned in. That period isn’t just about helping students over the finish line, but also accommodating a bunch of panicky colleagues and administrators scheduling last-minute meetings before people start disappearing for the summer.

Anyway. While I’ve not written much at all on the manuscript, I decided to take what time I could manage to work on my own organization, particularly all of the thousands of lines of source code I’m writing that’ll accompany the book.

Writing code for yourself or for your job is usually a bit different from writing code to teachothers. Even the code that I write in order to teach in the classroom is different from code I write to accompany books and articles: my usual way of prepping for code-intensive classes is to do a dry run and then have skeletal notes or sometimes more complete examples to refer from, if I’m teaching something extra complex and am likely to forget some small but essential detail in the middle of class. I don’t like just walking through canned, finished examples in class: live coding is how I roll.

In an instructional setting, even if it’s online because of the pandemic, there’s always the chance to go back and fix something later or, in the best cases, improve something on the spot in response to a student question or point of confusion. Writing code live makes for a better class than a shitty slide deck with completed examples, I think, but it also helps students sort of wrap their heads around the timescales and especially the process of writing code. As every developer knows, the process is never linear.

But when you’re writing code for a book or an article, you don’t have the luxury of refining things once the piece is published. Throughout the writing process, you’re building a foundation and guiding someone down a path that you, as the author, will have finished before the reader even starts out. And that means that you’ve got to do a lot more planning, as an author and a developer,to figure out what the reader’s journey is going to look like.

To smooth the way for themselves, the authors of some books and articles—too many books and articles, I’ll add—basically set up the code equivalent of a straw person: early examples so amateurishly written and poorly formed that they’re basically laughable. Of course, just like the straw-person argument, it’s easy to swoop in as the hero-author and make yourself look amazing by fixing crappy, amateurish code.

I don’t like that approach, though, and I avoid it in my own work. And this is why: from years of both reading a lot of these books as well as teaching them, I can say that the first examples readers see tend to make the deepest impressions. I notice this in my own work, when I make a mistake that a book deliberately showed me and only then admonished me not to make. I see the same thing happen in student work too, either when they repeat a mistake that they were shown in a book or a mistake that I showed off in class before clarifying it as a mistake. That pattern is annoying for readers, too: Why did we just spend all that time talking about this thing that you should never do?

So rather than starting from crappy code, I like to start with reasonably good code—which, just like the running copy of anything I write, is never the code that I draft.

The trick I’ve found, and the thing I’ve been working on for the last few weeks with my book, is to write the absolute best code you can on your own. And then you dial it back a few notches from there. Maybe that fancy ternary operator has to go, or that little shortcut method or piece of syntactic sugar: anything that would take time and space too much to explain to readers, especially when they’re first starting out. It doesn’t mean that you won’t ultimately get the code whipped into that shape, but that you don’t have to start there—and leave readers feeling lost by all the ancillary, look-how-smart-the-author-is stuff that can wait.

I do think it’s useful, however, to point out common mistakes after walking through a piece of code—especially when readers are expected to write it out themselves and run it. Beginners trying to pass a callback function in by reference in JavaScript, for a simple example, will very often include parentheses, so that the correct code on('event', callbackFunction); gets miswritten ason('event', callbackFunction());. It’s an easy mistake for beginners to make, because they’re used to seeing functions with parentheses attached, either the function definition— function someFunction() { } —or the place in the code where the function is called: someFunction().

The catch, of course, is when you as an author make a mistake in your own code. Alongside all of this, I’ve also been upping my automated testing game. (That’s included me bringing Nightwatch.js to the party. Testing WebRTC apps means having multiple, simultaneous browsers open for the duration of the test. Chrome can do that, but Gecko’s web driver implementation seems to be lagging somewhat. But this is all material for a whole other post.) Once I’ve got good-enough draft examples, I can’t help but continue to improve them. Sometimes the improvement is just about the code itself, but other times it’s about making the text read more gracefully. But even for books or articles, there’s no confidence in refactoring code without good test coverage. You’ve really not experienced BDD in full until you’re writing tests on code that you know will evolve a particular way over the length of a book.

One of the things I’m finding challenging about writing WebRTC code over a book-length work is that ideally the signaling and connection logic works completely separately and independently from any application logic. The application logic is what carries the examples throughout my book. At the same time, it’s too much to ask readers to write, say, fallbacks for older browsers in the signaling and connection code when they’re just getting started. So it’s necessary for me to keep track of gradual improvements to be made to the signaling and connection logic, even as I’m working through different examples with readers as they progress deeper into the book.

The latest strategy I’ve employed is to write the best, most thoroughly tested examples I can before I even begin to write a chapter. Then, as I write the chapter, I’m re-writing the completed example just as I expect a reader will. That frequently gives me insight as to the fancier or more complicated parts of my completed examples that I can save to guide readers through later.

So, that’s where I am. I’m ready to get back to churning out the running content of the book. And while I wish I had a few thousand more words to show for the last few weeks, I’m feeling pretty good that this code work is going to pave the way for me to better focus on how the book is put together—and how readers will work through it.

I'm Writing a Book about WebRTC for Pragmatic Programmers

Karl Stolley — Sun, 21 Mar 2021 23:25:30 +0000

I went from not even realizing I was going to write a book to having a signed contact with PragProg in 82 days: December 17, 2020 was the first day I worked in earnest on the proposal, and March 9, 2021 was the day I received and signed the contract.

I’d only just submitted the proposal itself eight days earlier, on March 1. At 9:18am. I note the time, because it was just 28 minutes later that I heard from an Author Relations contact at PragProg with some of the best words a writer can hear:

You’ve done a great job with the proposal and sample chapter, so I think I can present your proposal without any revisions. It’s clear that you get the PragProg style and I’m grateful for that fact and happy to hear you are using PragProg books in your classroom!

(Yes, I use PragProg books in the classroom all the time, and no, I wasn’t ashamed to slip that little detail into my proposal itself.)

Since signing the contract, I’ve just been getting up to speed with Prag’s publication system—which I’m contractually bound not to discuss in detail, and I can see why. It’s pretty great. I’ve also begun working with my development editor, and I can say that this is book project is fixing to be whatever the opposite of lonely is. It’s an incredibly collaborative effort already, and I’ve only just gotten started.

Okay, but what about the book? What’s it actually about? Let me try out my elevator pitch on you:

You’re a web developer. You’ve spent the pandemic racking up untold hours on Google Meet, Zoom, FaceTime, or whatever real-time video-chat service. But what you might not know is that all modern browsers ship with an implementation of a web API called WebRTC: Web Real-Time Communication Between Browsers. WebRTC allows you to build real-time applications that run directly in the browser. And sort of like with FaceTime or whatever, you can build your own video-chat app. Only unlike all of those popular services, WebRTC works peer to peer: the app you build directly connects one web browser to another. There’s no server involved. And video chatting is only just the most obvious example. With WebRTC, you can open up channels to exchange any arbitrary data that might power all kinds of real-time activities: text-based chats, secure peer-to-peer file transfers, collaborative brainstorming sessions, and even multiplayer gaming. This book will have you doing all of that. And not just with two connected peers: an entire chapter of the book is devoted to engineering multi-peer WebRTC apps, using a mesh-network architecture.

Okay. So that needs some work. But hopefully the gist of it comes across.

So where did the book come from? Last fall, I taught a course on WebRTC for the first time. As I wrote in the proposal, putting that class together didn’t go very smoothly:

The biggest challenge I faced in putting together my WebRTC class over the last year was the lack of a suitable, up-to-date book for teaching or engaging in self-study of WebRTC—especially in the context of web development. As I detail in the competing books section below, there are a few rapidly aging titles on the market that are now little more than works of history. There is little, in book form or otherwise, that offers a substantial, pragmatic application of the WebRTC specification as it has matured since achieving Candidate Recommendation status in late 2017. (The spec became a full W3C Recommendation on January 26, 2021, while I was preparing this proposal).

Having scoured the web for as many articles and resources as I could to try to structure my class, I still had to write a lot of material for students—especially source-code examples. It was only after the fog had lifted at the end of fall semester that I realized I might have the material necessary to actually write a book about the topic.

It was really important to me to have the class structured around the native WebRTC APIs found in the browser, rather than rely on a third-party library. The book will be the same, native-API deal: although I’ll be using Socket.IO as a signaling server, all of the client-side code uses nothing but the available browser APIs (occasionally with an assist from the adapter.js to shim certain browsers as needed).

So that’s my news. I’ll be posting about the book here as I write it. And you’re welcome to message me about it on Twitter @stolleydotdev, of course.

Dynamic Namespaces in Socket.io

Karl Stolley — Fri, 30 Oct 2020 23:42:55 +0000

I’m teaching socket.io as a convenient WebRTC signaling channel in my WebRTC class this semester. As part of prepping that, I finally had to sit down and figure out dynamic namespaces in socket.io. There is some really tricky business to namespaces, dynamic or otherwise, particularly when it comes to listening for messages and events server-side sent from connected clients on the namespace.

In short, namespaced sockets work differently on the client from how they do on the server.

On the client, we simply create a namespaced socket connection (ns, here with a Google Meet–like namespace of /jkl-mnop-qrs) and both listen and emit events on it directly:

// Client-side code (site.js)

var ns = io('/jkl-mnop-qrs'); // ordinarily set dynamically in JavaScript, somehow

ns.on('message', function(data) {
  console.log('Message received: ' + data);
});

document.querySelector('body').addEventListener('click', function(e) {
  console.log('Body was clicked');
  // the `send()` method is essentially shorthand for `emit('message', data)`;
  // that is, the `send()` method emits the `message` event for us:
  ns.send('Someone clicked the body element');
});

In that example, the listener ns.on(...) handles incoming messages and sends a pre-determined message to the socket server when someone clicks anywhere in the <body> element. Both use the ns object created from calling the io() constructor.

On the server, though, it’s a completely different, more complicated story.

// Server-side code (app.js)

const namespaces = io.of(/^\/[a-z]{3}-[a-z]{4}-[a-z]{3}$/);

namespaces.on('connection', function(socket) {
  const namespace = socket.nsp;

  // You can emit messages directly on the `namespace` object...
  namespace.emit('message', `Successfully connected on namespace: ${namespace.name}`);

  // ...BUT--BUT, BUT, BUT--you must listen for messages coming from the clients
  // on the socket (`socket`) object, NOT the namespace:
  socket.on('message', function(data) {
    console.log('A message was received from a client: ', data);
    // AND if you want to do a broadcast emit -- which sends the message to
    // all the connected clients *except* for the sender -- you MUST use the
    // socket object (`socket`), as the `namespace` does not understand the
    // `broadcast` method:
    socket.broadcast.emit('message', data);
  });
});

To summarize the content of the comments: you listen for connections on the namespaces that match the pattern in socket.of(...). You can emit messages on the namespace returned by namespaces.on(...), but you cannot listen for incoming messages or any other events on namespace. Instead, you listen on the socket object (socket) created on the connection event.

Additionally, if you want to broadcast a message (which sends the message to all connected clients except the sending client), you must use socket.broadcast.emit.

So a simplified version of the code above looks like this:

// Server-side code (app.js)

const namespaces = io.of(/^\/[a-z]{3}-[a-z]{4}-[a-z]{3}$/);

namespaces.on('connection', function(socket) {
  const namespace = socket.nsp;

  socket.emit('message', `Successfully connected on namespace: ${namespace.name}`);

  socket.on('message', function(data) {
    console.log('A message was received from a client: ', data);
    socket.broadcast.emit('message', data);
  });
});

Now the namespace variable is only being used for diagnostic purposes (Successfully connected on namespace: ${namespace.name}).

Everything else is listening or emitting on the socket object (socket) returned to the initial namespaces.on(...) callback on each client connection.

The thing that is tricky to grasp (and that cost me about 3 hours of my life) is that that socket object is unique to the connection on each namespace. This is not properly reflected ANYWHERE in socket.io’s documentation, which makes me crazy. And yes, I should write something and submit a pull request. I know.

WCAG 2.1's Seventeen New Success Criteria

Karl Stolley — Wed, 15 Jul 2020 17:38:02 +0000

I didn’t try my very hardest to find a list of all of the new Success Criteria in Web Content Accessibility Guidelines 2.1 (WCAG 2.1) that were not a part of WCAG 2.0, but if there is such a list, it’s not easy to find.

And given the formatting for WCAG 2.0, it’s not all that easy to make such a list, either. But in case this is helpful to anyone, here are the seventeen new Success Criteria in WCAG 2.1, which became a W3C Recommendation in June 2018, with links to each criterion in the specification:

1: Perceivable

1.3: Adaptable
- 1.3.4: Orientation
- 1.3.5: Identify Input Purpose
- 1.3.6: Identify Purpose
1.4: Distinguishable
- 1.4.10: Reflow
- 1.4.11: Non-text Contrast
- 1.4.12: Text Spacing
- 1.4.13: Content on Hover or Focus

2: Operable

2.1: Keyboard Accessible
- 2.1.4: Character Key Shortcuts
2.2: Enough Time
- 2.2.6: Timeouts
2.3: Seizures and Physical Reactions
- 2.3.3: Animation from Interactions
2.5: Input Modalities
- 2.5.1: Pointer Gestures
- 2.5.2: Pointer Cancellation
- 2.5.3: Label in Name
- 2.5.4: Motion Actuation
- 2.5.5: Target Size
- 2.5.6: Concurrent Input Mechanisms

4: Robust

4.1: Compatible
- 4.1.3: Status Messages

Note that Section 2.5: Input Modalities is the only entirely new section, and that there were no additional Success Criteria added under Section 3:Understandable.

Hey, Wait: Git Has a New Complaint

Karl Stolley — Sun, 28 Jun 2020 05:00:00 +0000

When you upgrade to Git 2.27, one of the first changes you’ll notice is Git issuing this dire warning every time you go to pull from a remote:

$ git pull origin main
warning: Pulling without specifying how to reconcile divergent branches is
discouraged. You can squelch this message by running one of the following
commands sometime before your next pull:

  git config pull.rebase false # merge (the default strategy)
  git config pull.rebase true # rebase
  git config pull.ff only # fast-forward only

You can replace "git config" with "git config --global" to set a default
preference for all repositories. You can also pass --rebase, --no-rebase,
or --ff-only on the command line to override the configured default per
invocation.

Almost certainly the best option here is to (probably globally) specify fast-forward only:

$ git config --global pull.ff only

A fast-forward is what happens under the happiest of circumstances: your local branch has no new changes that aren’t already on the remote, so you’re updating (fast-forwarding) the pointer on the HEAD commit to match the remote. Setting pull.ff only ensures that that happy behavior continues.

But there are plenty of unhappy circumstances. The one that most commonly ruins my day is when I’ve been working on the same branch of the same repo on two different computers. I push the commits from Computer A to the remote, but forget to run git pull from Computer B before writing new commits.

The default strategy, a merge commit, means you can end up with a repository full of merge commits from your own remote branch. It’s ugly and almost always leads to foxtrot commits.

By setting pull.ff only, Git will no longer race ahead and create a merge commit. You can opt to do so manually (git merge origin/main), but if you’re not working on a public branch, or if your divergent commits are still local, you can rebase your local branch onto the missing commits from your remote (git rebase origin/main). They’ll then appear as though they’ve been there the whole time.

Of course, when it comes to working with branches shared with others, it’s better by far to create your own, independent feature-branches and keep your work isolated, and rebase from the parent branch before pushing the commits on your own branch.

Cache-busting Assets with sed

Karl Stolley — Sat, 11 Apr 2020 05:00:00 +0000

Thanks to the ongoing quarantine, I’ve found the time to take on some of the long-standing items on my web dev to-do list. One of these items was to implement cache-busting on CSS and JavaScript assets in coordination with service workers.

Being a developer with an already strong but still growing aversion to frameworks and taskrunners, especially when all I really need is a simple feature, I prefer mining old-school Unix tools and using them to building out a custom deploy script, usually using a post-receive hook with Git. It’s hard to find an old-school tool as old as sed, which first appeared in 1974.

For those who don’t know sed (short for “streaming editor”), its friendly overviewpage opens with a fine summary:

sed is commonly used to filter text, i.e., it takes text input, performs some operation (or set of operations) on it, and outputs the modified text. sed is typically used for extracting part of a file using pattern matching or substituting multiple occurrences of a string within a file.

And that’s what I need: to comb through a static set of HTML files for references like <script src="assets/js/site.js"> and insert a hash so the file referenced becomes something likeassets/js/site.0a1cb23.js. The file itself remains site.js on the server, so I don’t have to worry about moving files around and changing their names. A quick little location-scoped regex rewrite block in Nginx will ignore the hash:

# This assumes assets off of an /assets directory, obviously
location ~ /assets {
  rewrite (.+)\.([a-f0-9]+)\.(js|css)$ $1.$3 break;
}

To grab a meaningful hash, I need to capture the HEAD commit hash from my site’s repository, usinggit rev-parse. As a side note, it’s essential to include the argument --git-dir=<bare repo directory> when trying to run commands on a specific repo—especially bare repos, which I use for all my basic deploy scripts.

So the relevant part of my deploy script (which is written for zsh and its awesome recursive globbing syntax looks something like this:

cd $TMP_GIT_CLONE
SHORTHASH=`git --git-dir=$TMP_GIT_CLONE/.git rev-parse --short HEAD`;
for file in **/*.html;
sed -E -i "s/=([^:]+)\.(css|js)/=\1.$SHORTHASH.\2/g" $file;
done;

With that run, the files have all of their paths updated. I then need to give a similar treatment to my service worker script, which actually needs a variable declaration rewritten.

For the sake of local development and not hanging on too long to an existing service worker cache, I open my service worker script with these lines JavaScript, which falls back to a mockTenMinuteVersion() function that generates a new time-based hash every ten minutes:

var VERSION;
const version = VERSION ? VERSION : mockTenMinuteVersion();

I prefer using the ES 2015 const declaration, but because const by definition cannot have its value reassigned, simply declaring const VERSION; is enough kick out a nasty little syntax error and prevent the rest of the script from running.

To allow for that, I write the regex on this call to sed to also replace var with const and assign the SHORTHASH value to const VERSION as well. These lines get added to thepost-receive lines listed above:

sed -E -i "s/var VERSION/const VERSION = \"$SHORTHASH\"/" _site/sw.js;
sed -E -i "s/'([^:]+)\.(css|js)/'\1.$SHORTHASH.\2/g" _site/sw.js;

And that changes the opening lines of my service worker script to:

const VERSION = "0a1cb23";
const version = VERSION ? VERSION : mockTenMinuteVersion();

Finally, sed needs to do its thing and update the files listed in the manifest of preloaded files togo from this:

const site_preloaded_assets = {
  essential: [
    '/assets/css/screen.css',
    '/assets/js/site.js',
    '/',
    site_offline_path
  ],
  supporting: []
};

to this:

const site_preloaded_assets = {
  essential: [
    '/assets/css/screen.0a1cb23.css',
    '/assets/js/site.0a1cb23.js',
    '/',
    site_offline_path
  ],
  supporting: []
};

Quoting in HTML: Quotations, Citations, and Blockquotes

Karl Stolley — Wed, 11 Dec 2019 03:37:00 +0000

John Rhea writes a beautifully detailed article about HTML semantics:

It’s all too common to see the incorrect HTML used for quotes in markup. In this article, let’s dig into all this, looking at different situations and different HTML tags to handle those situations.

Bonus points for including a creative use for the <figure> element for presenting a <blockquote> element with an attendant <cite>, and likewise the mention of the CSS hanging-punctuation property toward the end of the article.

`@supports` Shines Brightest on Dependent Styles

Karl Stolley — Wed, 13 Nov 2019 06:00:00 +0000

Feature queries via the @supports CSS at-rule provide syntax to conditionally apply a set of style declarations when a given feature is supported. It’s common to see web developers test and immediately apply a newer CSS property:

@supports(display: grid) {
  main { display: grid; }
}

But considering that browsers ignore CSS that they don’t understand, such applications of feature queries can be redundant and unncessary.

CSS shapes enable developers to draw outlines around floated content. Text will flow to conform
to the shape, as shown here. The hyphenation and justification, however, is only desirable when
CSS shapes are supported.

Where feature queries really shine, however, is in preventing dependent styles from being applied. Feature queries are exceptionally suited to applying properties browsers do understand, but that are only appropriate when a more advanced property is available.

For a recent example, I started experimenting with CSS Shapes on a floated image of a Raspberry Pi on my professional website (Save a visit to the website itself and see the figure).

I did not use a feature query on the shape-outsideproperty itself.

Instead, I used a feature query to prevent applying two other, more well supported features: justified text and hyphenation. The code looks like this:

@supports (shape-outside: polygon(0px 0px, 0% 0%)) {
  #about p {
    hyphens: auto;
    text-align: justify;
  }
}

I don’t want to use hyphens or text justification in the absence of the custom shape I drew around the Pi image. Their purpose is only to help the text better conform to the CSS shape and the image content. In the absence of CSS shapes support, a plain old rectangular float appears. And that’s fine. But there’s no need to bring hyphens or justification to that party, which will only further intensify the boxiness of that older-school design.

A couple of notes here to close out the post:

@supports rules require not just the property but also a valid value. The value polygon() is_not_ valid by itself, so I passed in some coordinates as zero values (with units, which is poor form). Consult the MDN documentation onshape-outside.
I highly recommend the Firefox CSS Shapes Editor, even though it feels to me like bizarro world using a WYSIWYG interface on newer CSS properties. The coordinates it generates are responsive, too, which is awesome.
I’m forever admonishing my students not to use justification. That is still the case for long passages of text. Run a ragged right-edge. It occurs to me that it might be wise to also check forhyphens support before applying justified text, although browser hyphenation itself is still a big work in progress.

Two-Value Display Properties in CSS

Karl Stolley — Mon, 28 Oct 2019 05:00:00 +0000

The incomparable Rachel Andrew introduces the brave new world of two-value CSS display properties:

the outer display type of an element is always block or inline, and dictates how the box behaves in the normal flow of the document. The inner display type then changes the formatting context of the children. To better describe this behavior, the CSS Display specification has been refactored to allow for display to accept two values. The first describes whether the outer display type is block or inline, whereas the second value describes the formatting of the children.

I’m of two minds for this change. On the one hand, this introduces some complexity (e.g., the venerable display: block is, in its two-value declaration, display: block flow). But on the other hand, with that complexity comes an invitation to web developers to better understand document flow and formatting context—to which Rachel Andrew’s book The New CSS Layout is an indispensable guide.

The two-value syntax for display is currently only available in Firefox 70, listed in the compatibility table at MDN under “multi-keyword values.”

Back to a Single Spec for HTML and the DOM

Karl Stolley — Sun, 20 Oct 2019 05:00:00 +0000

Coralie Mercer at the World Wide Web Consortium blog, back in May 2019:

Today W3C and the WHATWG signed an agreement to collaborate on the development of a single version of the HTML and DOM specifications. The Memorandum of Understanding jointly published as the WHATWG/W3C Joint Working Mode gives the specifics of this collaboration.

That announcement is now reflected in this pull request at the WHATWG. The return to a single, shared specification for HTML and another for the DOM is good news for developers, browser makers, and those of us who pitch in to make dev-friendly documentation over on MDN. It’s also important, I think, that the WHATWG “living standard” is what will live on, rather than the post-hoc versioned HTML 5.x specifications the W3C had been publishing.

DEV Community: Karl Stolley

Properly Configuring Nightwatch to Run Geckodriver

WebRTC Book Update: Revised TOC and Some More Legroom

Working to Get Off the Sidelines

I'm Writing a Book about WebRTC for Pragmatic Programmers

Dynamic Namespaces in Socket.io

WCAG 2.1's Seventeen New Success Criteria

1: Perceivable

1.3: Adaptable

1.4: Distinguishable

2: Operable

2.1: Keyboard Accessible

2.2: Enough Time

2.3: Seizures and Physical Reactions

2.5: Input Modalities