The lab

Dokploy’s installer expects a Linux server, so I ran it inside a Docker-in-Docker container. That keeps everything it does away from your own Docker.

docker run -d --privileged --name dokploy-lab \
  -p 8088:80 -p 3005:3000 docker:29-dind

docker exec dokploy-lab sh -c 'apk add --no-cache bash curl iproute2 openssl'

# the installer refuses to run inside a container, and Docker puts
# this file in every container, which is how it can tell
docker exec dokploy-lab rm -f /.dockerenv

curl -sSL https://dokploy.com/install.sh -o install.sh
docker cp install.sh dokploy-lab:/root/install.sh
docker exec dokploy-lab bash -c \
  'ADVERTISE_ADDR=$(hostname -i | awk "{print \$1}") bash /root/install.sh'

Skip the rm and the installer stops straight away, with an error that sends you looking in the wrong place:

Installing Dokploy version: v0.30.8
This script must be run on Linux

It is running on Linux. That’s the message the installer prints when it finds /.dockerenv, and it exits before touching anything.

One thing to know about the installer if you run it outside a container: it runs docker swarm leave --force before setting up its own swarm. That’s so a reinstall works, because docker swarm init refuses on a machine that’s already in a swarm:

Error response from daemon: This node is already part of a swarm.
Use "docker swarm leave" to leave this swarm and join another one.

Inside the lab container that’s harmless. On a machine already running Swarm services, it takes the machine out of that swarm.

Then the dashboard is at http://localhost:3005 and Dokploy’s Traefik answers on localhost:8088. This was Dokploy v0.30.8 with Traefik v3.6.25. It needs a few GB of disk, and mine ran out halfway through the first attempt, so check docker system df first.

The test app

In Dokploy I created a project, then a Compose service with the type set to Stack. That’s the setting that makes Dokploy run docker stack deploy instead of plain Compose. The provider is Raw, so the compose file is just pasted in:

services:
  web:
    image: httpd:alpine
    command: ["sh", "-c", "sleep 8; echo $$VERSION > /usr/local/apache2/htdocs/index.html; exec httpd-foreground"]
    environment:
      VERSION: v1

It’s a plain Apache web server (httpd:alpine is the official Apache image, Alpine flavour) told to do three things when the container starts, one after the other:

1. sleep 8 waits eight seconds before doing anything. A real app doesn’t answer the moment its container starts either: it connects to a database, runs migrations, warms up. The sleep stands in for that, so the container is running but not yet answering, which is exactly the gap a deploy has to handle.
2. echo $$VERSION > /usr/local/apache2/htdocs/index.html writes the version, v1, into the page Apache serves. The $$ is how you write a literal $ in a compose file; without it, Compose would try to fill $VERSION in itself when reading the file, instead of leaving it for the container’s shell. So every request returns just v1, and the probe can see the exact moment traffic moves from the old container to the new one.
3. exec httpd-foreground starts Apache, which listens on port 80. exec makes Apache replace the shell rather than run under it, so it’s Apache that receives the stop signal when Swarm shuts the container down.

To deploy a “new version”, I only change VERSION to v2, v3 and so on. Swarm sees a changed service and replaces the container.

Under Domains I added lab.localhost on port 80. Notice there are no Traefik labels and no network in the file. Dokploy adds both when it deploys.

The probe

A small Node script (Node 18 or later, no packages) that requests the app every 100 milliseconds and writes down what came back:

// probe.mjs, run with: node probe.mjs probe.log 60
import { appendFileSync, writeFileSync } from "node:fs";

const [out, seconds] = process.argv.slice(2);
const end = Date.now() + Number(seconds) * 1000;
writeFileSync(out, "");

while (Date.now() < end) {
  const started = Date.now();
  let line;
  try {
    const res = await fetch("http://lab.localhost:8088/", { signal: AbortSignal.timeout(1000) });
    const body = (await res.text()).trim();
    line = `${res.status} ${res.ok ? body : "-"}`;
  } catch (e) {
    line = `ERR ${e.name}`;
  }
  appendFileSync(out, `${(started / 1000).toFixed(2)} ${line}\n`);
  await new Promise((r) => setTimeout(r, Math.max(0, 100 - (Date.now() - started))));
}

Start it, change VERSION in Dokploy, press Deploy, then count what came back:

cut -d' ' -f2- probe.log | sort | uniq -c

One thing that cost me a few minutes: the obvious way to write this is fetch("http://localhost:8088/", { headers: { Host: "lab.localhost" } }), and it doesn’t work. Node’s fetch quietly replaces your Host header with the one from the URL, so Traefik sees localhost and answers 404 for every request, which looks exactly like a broken deploy. I checked with a tiny server that echoes the header back: fetch sent localhost:18099, while node:http sent lab.localhost. Putting the hostname in the URL avoids the problem, because *.localhost resolves to your own machine.

Reading the results

Each step below shows what the probe saw during one deploy, as a timeline of what came back. A failed request is one of three things, and each has a different cause:

• 404: Traefik has no container to send the request to, so it answers “404 page not found” itself.
• 502: Traefik sent the request to a container that refused it, usually one that’s stopping or hasn’t started listening yet. A visitor sees “Bad Gateway”.
• timeout: Traefik sent the request to a container address that no longer exists, and nothing came back. The probe gives up after a second; a visitor’s browser just hangs.

Step 0: Dokploy’s defaults

The first deploy, v1 to v2, with nothing changed from what Dokploy does on its own:

v1 answering
502      for 1s     old container stopping, Traefik still sending to it
timeout  for 1s     old container gone, Traefik still sending to its address
404      for 14s    Traefik has nothing to send to
v2 answering

145 requests failed, over about 16 seconds.

Here’s why. Swarm’s default update order is stop-first: it stops the old container first, then starts the new one. So from the moment the old one stopped, there was nothing to serve the app until the new one had started, finished its 8-second sleep, and Traefik had noticed it. That last part is the long 404.

You can see the order Dokploy deployed with:

docker service inspect <service> --format '{{.Spec.UpdateConfig.Order}}'

which printed stop-first.

Step 1: start-first

deploy:
  update_config:
    order: start-first
    failure_action: rollback

start-first reverses the order: start the new container, and only then stop the old one. failure_action: rollback means that if the new one fails, Swarm puts the old one back.

v2 answering
502      for 5s     new container started but not listening yet
v3 answering

50 requests failed, over about 5 seconds. Better, but not zero.

This time the failures came from the new container. Swarm waits for the new container to be running before stopping the old one, and without a healthcheck, running only means the process has started. Mine was still in its sleep 8, with Apache not started yet. Swarm stopped the old container anyway, Traefik moved traffic to the new one, and the new one refused every request until Apache came up.

Step 2: a healthcheck

The fix for that is a healthcheck, so “ready” means “actually answers”:

healthcheck:
  test: ["CMD-SHELL", "wget -q -O- http://127.0.0.1/ || exit 1"]
  interval: 5s
  timeout: 3s
  retries: 3
  start_period: 20s

Docker runs the test command inside the container every interval. Exit code 0 means healthy. start_period gives the app 20 seconds to boot before failed checks count against it, and retries is how many failures in a row mark it unhealthy. Swarm now waits for the new container to report healthy before stopping the old one.

httpd:alpine ships busybox’s wget, so that’s what the check uses. Use whatever your own image actually has: a healthcheck that calls a program the image doesn’t include can never pass.

Some deploys now came through clean, so I ran it 11 times. 7 of the 11 still dropped between 7 and 20 requests, over 0.6 to 10 seconds. The other 4 dropped none. A typical bad one:

old container answering
502      for 1s     old container stopping, Traefik still sending to it
timeout  for 10s    old container gone, Traefik still sending to its address
new container answering

The new container was healthy the whole time, so this isn’t Swarm any more. The failures are all at the old container’s address, after Swarm stopped it: Traefik kept routing there. A gap that only shows up some of the time is exactly the kind that gets through testing. The next step shows why Traefik lags.

One tip if your own app sits behind Traefik: if it redirects HTTP to HTTPS (ASP.NET Core’s UseHttpsRedirection does), the healthcheck gets a 307 instead of a 200 and fails. Send the header Traefik sends, and the app answers instead of redirecting:

wget -q --header='X-Forwarded-Proto: https' -O- http://127.0.0.1:5000/health || exit 1

Step 3: the Traefik label

Those failures come from Traefik, not Swarm. Here’s the config Dokploy writes for its Traefik:

providers:
  swarm:
    exposedByDefault: false
    watch: true

No refreshSeconds, so the Swarm provider uses its default of 15 seconds. Traefik routes to each container’s own IP address and refreshes that list on its own schedule. To see it happen, I read Traefik’s backend list from its API every few hundred milliseconds during a redeploy:

t=0s   traefik: 10.0.1.25  | containers: .25 healthy, .26 starting
t=10s  traefik: 10.0.1.25  | containers: .25 healthy, .26 healthy
t=14s  traefik: 10.0.1.25  | containers: .25 stopping, .26 healthy
t=15s  traefik: 10.0.1.26  | containers: .26 healthy

The new container was healthy at 10 seconds and Traefik didn’t add it. At 14 seconds the old one was shutting down and Traefik was still sending it traffic. It caught up at 15. How long that gap lasts depends on where the switch lands in Traefik’s refresh cycle, which is why some runs lose nothing and others lose ten seconds.

One label fixes it:

deploy:
  labels:
    traefik.swarm.lbswarm: "true"

With it, Traefik stops tracking individual containers. It sends every request to the service’s virtual IP, one address that stays the same across deploys, and Swarm’s own load balancer behind that address picks a container. Swarm is also the one starting and stopping the containers, so it takes the old one out of rotation as part of stopping it. There’s no second system that has to notice, so no window where traffic goes to an address that’s gone. Dokploy merges this label with the routing labels it generates, so nothing else needs adding.

0 requests failed, across 10 deploys. Same app, same healthcheck, same probe. The only difference from the 7-out-of-11 above is this label.

That name is for Traefik v3, which is what Dokploy ships. On Traefik v2 the label is traefik.docker.lbswarm.

The results

A few more things

Dokploy’s “Done” doesn’t mean it deployed. If the new container never becomes healthy, Swarm rolls back and the old one keeps serving, which is what you want. But Dokploy runs docker stack deploy, which returns as soon as the update is handed to Swarm, so its Deployments tab still shows Done in green. Ask Swarm instead:

$ docker service inspect <service> --format '{{.UpdateStatus.State}}'
rollback_completed

Make sure only one thing triggers a deploy. Swarm updates a service one change at a time. Each change is made against the service’s current version, and if two arrive at the same moment, the second is made against a version that no longer exists. Swarm rejects it instead of guessing how to combine them. I tested it by sending two updates to the lab service at the same instant. One went through, and the other failed with:

Error response from daemon: rpc error: code = Unknown desc = update out of sequence

You won’t do that by hand, but it’s easy to set up by accident: two things that each deploy when you push. For example, a CI pipeline that calls Dokploy’s deploy webhook after building the image, and Dokploy’s own Autodeploy, which deploys on every push to the branch. One push, two deploys a second apart, and one of them fails.

The fix is to pick one trigger. If CI calls the webhook, switch Autodeploy off on the service in Dokploy, or set it to deploy only on tags, so the webhook is the only thing that starts a deploy.

The old and new versions overlap. With start-first, both containers run at the same time for a few seconds, against the same database. If your new version’s migration drops or renames a column the old version still reads, the old container starts erroring during the window that was supposed to be safe. So add first, deploy, and remove the old column in a later release.

And if your app has slow requests, stop_grace_period gives the old container longer than the default 10 seconds to finish them after it’s told to stop.

The final compose file

services:
  web:
    image: httpd:alpine
    command: ["sh", "-c", "sleep 8; echo $$VERSION > /usr/local/apache2/htdocs/index.html; exec httpd-foreground"]
    environment:
      VERSION: v6
    healthcheck:
      test: ["CMD-SHELL", "wget -q -O- http://127.0.0.1/ || exit 1"]
      interval: 5s
      timeout: 3s
      retries: 3
      start_period: 20s
    deploy:
      labels:
        traefik.swarm.lbswarm: "true"
      update_config:
        order: start-first
        failure_action: rollback

When you’re done, one command removes the whole lab:

docker rm -f -v dokploy-lab

Thanks !!!

The post Zero-downtime deployments in Dokploy with Docker Swarm appeared first on Swacblooms🦋.

The setup

Docker Swarm on one VPS. Postgres and cloudflared on an overlay network, nothing published:

services:
  postgres:
    image: postgres:18-alpine
    volumes:
      - postgres-data:/var/lib/postgresql   # not /data, postgres:18 changed this
    networks:
      internal-net:
        aliases:
          - postgres.internal.service   # the hostname I want to reach it by

  cloudflared:
    image: cloudflare/cloudflared:latest
    command: tunnel --no-autoupdate run --token ${CLOUDFLARE_TUNNEL_TOKEN}
    networks: [internal-net]

networks:
  internal-net:
    driver: overlay
    attachable: true          # matters later
    ipam:
      config:
        - subnet: 10.55.0.0/24

On the Cloudflare side, you tell the tunnel which addresses it owns: in Zero Trust under Networks → Routes, add a CIDR route for 10.55.0.0/24 pointing at this tunnel. That single route is what lets WARP reach anything on the overlay, database and DNS server alike.

It’s also why the subnet is pinned in the compose file. Cloudflare stores that CIDR by value, so if Docker allocated the subnet dynamically, a recreated network could land on a different range and the route would silently point at nothing.

So the flow is: cloudflared dials out to Cloudflare, WARP on the laptop routes 10.55.0.0/24 into the tunnel, Access policies decide who gets in. In theory you then add a “private hostname” route on top and you’re done.

What actually broke

Split Tunnels blocks everything silently. WARP’s default exclude list contains 10.0.0.0/8, which covers my overlay, plus most of 100.64.0.0/10, the range Cloudflare itself uses for tunnel routing. Excluded means “don’t send through the tunnel”, so WARP treated my database like a local LAN address and the packets went nowhere. No error on either side. You have to delete those entries from the device profile.

Gateway proxy needs UDP. The dashboard calls it “recommended”, the docs say it’s required for DNS to internal resolvers. Believe the docs.

Don’t name anything .local. macOS hardwires .local to multicast DNS:

$ scutil --dns | grep -A2 "domain.*: local"
resolver #2
  domain   : local
  options  : mdns

The query never leaves your Mac, so no Cloudflare setting can fix it. Cloudflare’s own docs use wiki.internal.local as their example, which is a trap. .internal also fails, for a different reason: it’s in WARP’s Local Domain Fallback list, so queries get diverted to your local resolver. I ended up on a made-up suffix that’s on nobody’s special list.

And after all that, private hostnames still didn’t resolve. Querying Gateway’s DoH endpoint directly (the only check that bypasses all the caching):

curl -s -H 'accept: application/dns-json' \
  "https://<your-team>.cloudflare-gateway.com/dns-query?name=db.internal&type=A"

{"Status":3, "Authority":[{"data":"a.root-servers.net. ..."}]}

Gateway was sending my private hostname to the public DNS root instead of consulting my route. The reason was a banner on a different dashboard page: “Your account does not have access to Internal DNS. Contact your account team to join the closed beta.” Private hostname routes depend on that beta. Being account admin doesn’t help, it’s an entitlement, not a permission.

The workaround: bring your own DNS

Cloudflare supports pointing Gateway at your own DNS server on any plan. And Docker already runs a DNS server that knows every service by name, at 127.0.0.11 inside each container. It’s not reachable from outside, but a container on the same network can forward to it.

Important part: this container does not go into the Swarm stack. It’s a separate, plain Compose file that you run with docker compose up -d on the same host, attached to the Swarm network from outside. The reason is coming in the next section, but the short version is that Swarm won’t let you pin its IP and Compose will.

# dns/compose.yaml, run with: docker compose up -d
name: myapp-dns

services:
  dns:
    image: 4km3/dnsmasq:2.90-r3
    command: -k --server=127.0.0.11 --no-resolv --log-queries --log-facility=-
    networks:
      internal-net:
        ipv4_address: 10.55.0.60
    restart: unless-stopped

networks:
  internal-net:
    external: true
    name: myapp_internal-net

That’s the entire DNS server. 15MB image, half a megabyte of RAM, no config file. --log-facility=- is the flag you’ll wish you knew about: without it dnsmasq logs to syslog inside the container and docker logs shows nothing, which looks exactly like a broken container.

Reaching dnsmasq needs no extra Cloudflare routing, by the way. It sits at 10.55.0.60, inside the CIDR route you already created.

Where does the hostname itself come from? The aliases line on the postgres service in the first compose file. Docker’s embedded DNS registers dotted aliases directly, so postgres.internal.service already resolves inside the network with no rewrite rules anywhere. dnsmasq just makes that answer reachable by Gateway.

Then one resolver policy in Zero Trust: domain is internal.service, resolver 10.55.0.60:53, marked Private on your virtual network. Matching the shared suffix instead of the full name means the policy also covers every subdomain, so a future redis.internal.service or minio.internal.service works the moment you add its alias. No dashboard changes ever again.

The Swarm static IP problem

Notice the ipv4_address: 10.55.0.60 above. The resolver policy references the DNS server by IP, so that address must never move. Here’s the catch: Docker Swarm can’t pin container IPs, and worse, it silently ignores the config. I tested it:

    networks:
      mynet:
        ipv4_address: 10.66.0.50   # requested

The container came up on 10.66.0.3. No error, no warning. moby/moby#24170 has been open about this since 2016.

That’s why the dnsmasq file above is a standalone Compose deployment and not a service in the stack. Standalone containers do honour ipv4_address, and plain docker compose up -d creates standalone containers. Two things make the combination work: the Swarm network is marked attachable: true (now you know why), and the Compose file references it as external instead of creating its own. One gotcha: Swarm prefixes everything a stack creates, so a network declared as internal-net in a stack called myapp really exists as myapp_internal-net, and that’s the name the compose file must use.

If you forget attachable, at least this one fails loudly:

PermissionDenied: network myapp_internal-net not manually attachable

Trade-off: the DNS container isn’t part of docker stack deploy anymore, so deploys are two commands instead of one. Fine for one container, bad idea for half your stack.

Debugging notes

Local tools lie. dig and ping serve cached answers for up to a minute after a change, and WARP caches on top of that. I twice “confirmed” something that was actually broken. The DoH curl above is the only honest check.

Also, WARP doesn’t pick up policy or profile changes until you warp-cli disconnect && warp-cli connect. I spent a while debugging a policy that was already correct.

The result

laptop → WARP → Cloudflare Gateway
                   ├── resolver policy: *.internal.service → 10.55.0.60
                   └── tunnel → cloudflared → overlay
                                    ├── dnsmasq (10.55.0.60) → Docker DNS
                                    └── postgres (10.55.0.5:5432)

postgres.internal.service:5432 in any database client, with WARP on. No open ports, no public DNS, and adding a new service to the network is one alias line.

Thanks !!!

The post Cloudflare Tunnel to Postgres, plus Swarm’s static IP problem appeared first on Swacblooms🦋.

Blend peppers → Fry the stew → Combine with parboiled rice → Simmer → Serve

You cannot combine the rice with a stew that doesn’t exist yet. You cannot serve rice that’s still crunchy. And if you fry the plantain too early, it will be cold and sad by serving time, and people will talk about you.

But here’s the thing. A real cook doesn’t do these strictly one at a time. While the stew is frying on one burner, the rice is parboiling on another. That’s not cheating; that’s efficiency. Every party cook in your family is secretly running a topological sort in their head, a parallel one at that, and they didn’t even go to computer science school for it.

Now imagine you’re not a human cooking jollof, but a build system trying to figure out which files to compile first or a package manager installing dependencies so your app doesn’t crumble like a house built on sand

This is where Kahn’s Algorithm comes in. It’s a beautifully simple way to sort things that depend on other things, using nothing but graphs, patience, and a queue.

Here’s what our jollof “dependency graph” actually looks like. Notice it’s not a straight line, it’s more like a river with tributaries joining up:

Three of these tasks have no arrows pointing at them: “Blend Peppers”, “Parboil Rice”, and “Fry Plantain”. In graph terms, they have an in-degree of 0. No prerequisites, free to start immediately. And since none of them depends on each other, they can all happen at the same time on different burners. Meanwhile, “Combine Rice + Stew” has an in-degree of 2, so it’s blocked until both the stew and the rice are ready, no matter how impatient you are.

First, What’s a Topological Sort?

A topological sort takes a Directed Acyclic Graph (DAG, fancy term, don’t panic) and lines up all the nodes in an order where every arrow points forward. If there’s an arrow from A to B, then A has to show up before B in the final lineup. Like a very strict, very orderly buffet line.

Two rules for the graph:

1. Directed: the arrows only go one way. Stew comes before rice, not the other way around, unless you enjoy chaos and soggy disappointment.
2. Acyclic: no loops. If the rice depends on the stew and the stew somehow depends on the rice, you’ve created a paradox, and nobody at this party is eating tonight.

Kahn’s Algorithm

Kahn’s Algorithm is basically how a well-run kitchen operates. Here’s the plan in plain English:

1. Count the “in-degree” of every task, meaning how many arrows are pointing at it. “Blend peppers” has zero prerequisites. “Serve” has a whole queue of them.
2. Find the tasks with in-degree 0. These have no prerequisites and can start immediately. Blending peppers doesn’t wait for anybody.
3. Throw those tasks in a queue and process them one at a time. When you finish a task, remove its outgoing arrows. This might unlock new tasks whose in-degree just dropped to 0, so throw those in the queue as well. Once the stew is fried, the rice is cleared for entry.
4. Repeat until the queue is empty.
5. If you processed every task, you have your cooking order. If some tasks never got processed, there’s a cycle somewhere. A group of tasks stuck in an infinite “no, you first” standoff, like two aunties at the door insisting the other one enter first.

That’s it. No recursion required, no fancy backtracking. Just counting, queueing, and mild bookkeeping. It’s the algorithmic equivalent of prepping your ingredients before you turn on the stove.

Why Do We Even Need This?

Because the real world is obsessed with dependencies:

• Build systems (like make, MSBuild, or npm scripts) need to compile files in the right order.
• Task schedulers need to know Task B can’t start until Task A finishes.
• Course prerequisites in a university system.
• Package managers figuring out which dependency to install first.
• Spreadsheet formulas, where cell C1 can’t calculate until A1 and B1 are done.

Basically, anywhere you hear “you can’t do X until Y is finished”, Kahn’s Algorithm is quietly available to save the day, wearing a little apron.

A Quick Note on Parallel Cooking

One nice bonus before we write any code. Everything sitting in the queue at the same moment has zero unfinished prerequisites, which means none of those tasks depends on each other. So they can all run in parallel. That’s why you can blend peppers, parboil rice, and fry plantain all at once on three burners without breaking anything.

This is exactly how real systems parallelise work too. When npm installs 47 packages in seconds, or a build system compiles independent modules on all your CPU cores at once, it’s leaning on this same property of the graph. Your kitchen instincts and a modern CI/CD pipeline are running the same algorithm. The pipeline just doesn’t get to eat afterwards.

For this article, though, we’ll keep the code simple and stick to the classic one-task-at-a-time version.

The C# Code

Let’s build it. We’ll represent our graph as a dictionary of nodes to their list of neighbours, meaning “things that depend on me”.

using System;
using System.Collections.Generic;
using System.Linq;

public class KahnsTopologicalSort
{
    // The graph: key = a task, value = list of tasks that depend on it
    private readonly Dictionary<string, List<string>> _graph = new();

    // Track how many prerequisites each task has (in-degree)
    private readonly Dictionary<string, int> _inDegree = new();

    public void AddNode(string node)
    {
        if (!_graph.ContainsKey(node))
        {
            _graph[node] = new List<string>();
            _inDegree[node] = 0;
        }
    }

    // "from" must happen before "to" (e.g., AddEdge("Fry Stew", "Combine Rice + Stew"))
    public void AddEdge(string from, string to)
    {
        AddNode(from);
        AddNode(to);

        _graph[from].Add(to);
        _inDegree[to]++;
    }

    public List<string> Sort()
    {
        var result = new List<string>();
        var queue = new Queue<string>();

        // Step 1: find every task with no prerequisites
        foreach (var node in _inDegree.Keys)
        {
            if (_inDegree[node] == 0)
                queue.Enqueue(node);
        }

        // Step 2: process the queue like a head chef calling out orders
        while (queue.Count > 0)
        {
            var current = queue.Dequeue();
            result.Add(current);

            foreach (var neighbor in _graph[current])
            {
                _inDegree[neighbor]--;

                // If this task's prerequisites are all cleared, it's go time
                if (_inDegree[neighbor] == 0)
                    queue.Enqueue(neighbor);
            }
        }

        // Step 3: if we didn't process every task, there's a cycle
        if (result.Count != _graph.Count)
        {
            throw new InvalidOperationException(
                "Cycle detected! Two tasks are stuck saying 'no, after you' " +
                "forever, like aunties at a doorway. Go untangle your graph.");
        }

        return result;
    }
}

Trying It Out: Cooking Jollof, Programmatically

var jollof = new KahnsTopologicalSort();

jollof.AddEdge("Blend Peppers", "Fry Stew");
jollof.AddEdge("Fry Stew", "Combine Rice + Stew");
jollof.AddEdge("Parboil Rice", "Combine Rice + Stew");
jollof.AddEdge("Combine Rice + Stew", "Simmer");
jollof.AddEdge("Simmer", "Serve");
jollof.AddEdge("Fry Plantain", "Serve");

var order = jollof.Sort();
Console.WriteLine(string.Join(" -> ", order));
// Something like:
// Blend Peppers -> Parboil Rice -> Fry Plantain -> Fry Stew
//   -> Combine Rice + Stew -> Simmer -> Serve

Notice how all three prerequisite-free tasks come out first, before anything that depends on them. The output isn’t uniquely determined either. “Fry Plantain” could show up anywhere before “Serve”, since nothing else depends on it. Kahn’s Algorithm guarantees a valid order, not the only valid order. Nobody said this algorithm was bossy.

Bonus: Catching a Cycle

var brokenRecipe = new KahnsTopologicalSort();
brokenRecipe.AddEdge("Learn Grandma's Recipe", "Cook the Jollof");
brokenRecipe.AddEdge("Cook the Jollof", "Learn Grandma's Recipe");

try
{
    brokenRecipe.Sort();
}
catch (InvalidOperationException ex)
{
    Console.WriteLine(ex.Message);
    // "Cycle detected! Two tasks are stuck saying 'no, after you' forever..."
}

Grandma says you can’t cook the jollof until she’s taught you the recipe. Grandma also insists the only real way to learn the recipe is to cook it yourself. So cooking is waiting on learning, and learning is waiting on cooking. Neither task can ever start, neither in-degree ever reaches 0, the queue starts empty and stays empty, and Kahn’s Algorithm throws an exception. It’s the same energy as needing experience to get a job and a job to get experience. Some graphs cannot be sorted, only endured.

Wrapping Up

Kahn’s Algorithm is really just:

“Find the tasks with no prerequisites, do them, cross them off, see what opens up next, repeat.”

Which, honestly, is also how every great party cook operates. Three burners going, one eye on the stew, and a plan for what unlocks next. Whether you’re compiling code, scheduling parallel tasks, or making sure the stew and the rice meet each other at exactly the right moment, Kahn’s got your back. And now, so does your C# code.

Go forth and sort responsibly. And keep the “tasters” away from the pot.

The post The Topological Sort appeared first on Swacblooms🦋.

In this post we’ll build a perceptron in C#, train it on the famous Iris dataset, and understand every line along the way.

The Algorithm — Before Any Code

The basic idea

Imagine you’re trying to teach a friend to tell apart apples and oranges, but they can only feel the fruit — not see it. You let them feel the weight and the texture, and each time they guess wrong, you say “warmer” or “colder” and they adjust their judgment slightly.

That’s exactly what a perceptron does. It looks at numbers (the measurements), makes a guess, gets told whether it was right or wrong, and nudges itself to do better next time.

What “learning” actually means

The perceptron has two things it can adjust:

• Weights — one number per input feature. A high weight means “this feature matters a lot”. A weight close to zero means “this feature barely matters”.
• Bias — a single extra number that shifts the decision up or down, independent of the inputs.

At the start, weights are random small numbers. The perceptron has no idea what it’s doing. After seeing enough examples and correcting itself each time, the weights settle into values that produce the right answer.

The three steps it repeats

For every example in the training data, the perceptron does exactly three things:

1. Make a prediction

Multiply each input by its weight, add them all up, add the bias. If the total is 0 or above, predict class 1. If below zero, predict class 0.

prediction = (input₁ × weight₁) + (input₂ × weight₂) + bias  ≥ 0 ?  → 1 : 0

2. Calculate the error

Compare the prediction to the correct answer:

error = correct answer - prediction

If the prediction was right, error = 0 and nothing changes. If it predicted 0 but the answer was 1, error = +1 → weights need to go up. If it predicted 1 but the answer was 0, error = -1 → weights need to come down.

3. Update the weights

new weight = old weight + (learning rate × error × input)
new bias   = old bias   + (learning rate × error)

The learning rate is a small number (like 0.1) that controls how aggressively it corrects itself. Too large and it overcorrects and oscillates. Too small and it learns very slowly.

Notice that inputs with larger values cause larger weight updates. If one feature is always tiny, it won’t influence the weights much. This is intentional, big inputs carry more signal.

A concrete example

Say we have one flower with sepal length 5.1 and petal length 1.4, and it’s a Setosa (correct answer = 0).

• Current weights: [0.02, -0.01], bias: 0.0
• Net input: (5.1 × 0.02) + (1.4 × -0.01) + 0.0 = 0.102 - 0.014 = 0.088
• Prediction: 0.088 ≥ 0 → predict 1
• Error: 0 - 1 = -1 (wrong — should have been 0)
• Update with learning rate 0.1:
  • weight₁ = 0.02 + (0.1 × -1 × 5.1) = 0.02 - 0.51 = -0.49
  • weight₂ = -0.01 + (0.1 × -1 × 1.4) = -0.01 - 0.14 = -0.15
  • bias = 0.0 + (0.1 × -1) = -0.1

Next time it sees this flower, the lower weights will produce a lower net input, making it less likely to predict 1. Over many examples it finds the right balance.

When does it stop learning?

Either after a fixed number of passes through the data (epochs), or when it makes zero mistakes on a full pass, meaning it has found weights that correctly classify every example.

This is only guaranteed to happen if the two classes can be separated by a straight line. If they can’t, the perceptron will never settle, it will keep adjusting forever. That limitation is what led to the invention of multi-layer neural networks.

What is a Perceptron?

A perceptron is a binary classifier, it looks at some input numbers and decides: is this thing in group A or group B?

Think of it like a light switch with a dimmer. You feed it some numbers, it adds them all up (with some weights applied), and if the total is high enough, the switch flips on (class 1). If not, it stays off (class 0).

input 1 × weight 1 ┐
input 2 × weight 2 ├──→ sum + bias ──→ is it ≥ 0? ──→ yes=1 / no=0
input 3 × weight 3 ┘

The clever part: if it gets the answer wrong, it adjusts the weights slightly so it does better next time. Do this enough times and it learns to classify correctly.

The Dataset

We’ll use the Iris dataset, a classic. It contains measurements of 150 iris flowers across three species. We’ll only use two species (Setosa and Versicolor) to keep it a binary problem, and two features: sepal length and petal length.

Let’s load it directly from the UCI repository:

static async Task<(double[][] X, int[] y)> LoadIrisAsync()
{
    const string url = "https://archive.ics.uci.edu/ml/machine-learning-databases/iris/iris.data";
    using var client = new HttpClient();
    string csv = await client.GetStringAsync(url);

    var X = new List<double[]>();
    var y = new List<int>();

    foreach (var line in csv.Split('\n'))
    {
        var parts = line.Trim().Split(',');
        if (parts.Length < 5) continue;

        string label = parts[4];
        if (label != "Iris-setosa" && label != "Iris-versicolor") continue;

        // sepal length (col 0) and petal length (col 2)
        X.Add([double.Parse(parts[0]), double.Parse(parts[2])]);
        y.Add(label == "Iris-setosa" ? 0 : 1);
    }

    return (X.ToArray(), y.ToArray());
}

X is our feature matrix, each row is one flower, each column is one measurement. y is our label array — 0 for Setosa, 1 for Versicolor.

The Perceptron Class

public class Perceptron(double eta = 0.01, int epochs = 50, int randomState = 1)

Three parameters:

• eta (learning rate) — how big a step the perceptron takes when it adjusts weights. Too high and it overshoots; too low and it learns painfully slowly.
• epochs — how many full passes through the training data.
• randomState — a seed for the random number generator so results are reproducible.

Step 1: Initialise the Weights

Weights = new double[X[0].Length];
for (int i = 0; i < Weights.Length; i++)
    Weights[i] = NextGaussian(rng, mean: 0.0, stdDev: 0.01);

Bias = 0.0;

We start with tiny random weights (very close to zero) rather than all zeros. If everything started at zero, every weight would update by exactly the same amount each step and they’d never diverge — the perceptron would never learn different things from different features.

Bias is an extra number added to the sum that lets the decision boundary shift away from the origin.

Step 2: Train (the Fit loop)

for (int _ = 0; _ < epochs; _++)
{
    int errors = 0;
    for (int i = 0; i < X.Length; i++)
    {
        double update = eta * (y[i] - Predict(X[i]));
        for (int j = 0; j < Weights.Length; j++)
            Weights[j] += update * X[i][j];
        Bias += update;
        if (update != 0.0) errors++;
    }
    ErrorsPerEpoch.Add(errors);
}

For each flower in the training data:

1. Make a prediction — does it think this is Setosa (0) or Versicolor (1)?
2. Calculate the error — target - prediction. If it was right, this is 0. If wrong, it’s either +1 or -1.
3. Adjust the weights — multiply the error by the learning rate and by each input feature, then add that to the weight. Features that were large get a bigger nudge.
4. Adjust the bias — same idea, just without the feature multiplication.

If update is 0 the prediction was correct and nothing changes. The perceptron only learns from its mistakes.

After each epoch we record how many mistakes were made (ErrorsPerEpoch). A well-trained perceptron will show this number trending down toward zero.

Step 3: Predict

public double NetInput(double[] X)
{
    double result = Bias;
    for (int i = 0; i < Weights.Length; i++)
        result += X[i] * Weights[i];
    return result;
}

public int Predict(double[] X) => NetInput(X) >= 0.0 ? 1 : 0;

NetInput is the weighted sum: multiply each feature by its weight, add the bias, and return the total.

Predict applies the unit step function: if the sum is 0 or above, predict class 1; otherwise predict class 0. That’s the threshold the perceptron uses to make its decision.

Putting it all together

var (X, y) = await LoadIrisAsync();

var ppn = new Perceptron(eta: 0.1, epochs: 10, randomState: 42);
ppn.Fit(X, y);

Console.WriteLine("Weights: " + string.Join(", ", ppn.Weights.Select(w => w.ToString("F4"))));
Console.WriteLine("Bias: " + ppn.Bias);
Console.WriteLine("Errors per epoch: " + string.Join(", ", ppn.ErrorsPerEpoch));
Console.WriteLine("Prediction for [5.1, 1.4]: " + ppn.Predict([5.1, 1.4]));

Run this and you’ll see something like:

Loaded 100 samples from UCI
Weights: -0.3715, 0.9307
Bias: -0.2
Errors per epoch: 1, 3, 3, 2, 1, 0, 0, 0, 0, 0
Prediction for [5.1, 1.4]: 0

The errors start at 1, climb slightly as the weights adjust, then settle to zero by epoch 6, the perceptron has learned to correctly separate the two flower species. The prediction of 0 for [5.1, 1.4] is correct — that’s a Setosa flower.

Why Does This Work?

The two flower species happen to be linearly separable: if you plot them on a graph by sepal length and petal length, you can draw a straight line that separates them cleanly. The perceptron finds that line.

This is also the perceptron’s main limitation: if the data can’t be separated by a straight line, it will never converge. That’s what motivated the invention of multi-layer neural networks — stacking perceptrons so they can learn curved, complex boundaries.

But for linearly separable problems, the original 1958 perceptron still works perfectly.

Full Code

var (X, y) = await LoadIrisAsync();

var ppn = new Perceptron(eta: 0.1, epochs: 10, randomState: 42);
ppn.Fit(X, y);

Console.WriteLine("Weights: " + string.Join(", ", ppn.Weights.Select(w => w.ToString("F4"))));
Console.WriteLine("Bias: " + ppn.Bias);
Console.WriteLine("Errors per epoch: " + string.Join(", ", ppn.ErrorsPerEpoch));
Console.WriteLine("Prediction for [5.1, 1.4]: " + ppn.Predict([5.1, 1.4]));

static async Task<(double[][] X, int[] y)> LoadIrisAsync()
{
    const string url = "https://archive.ics.uci.edu/ml/machine-learning-databases/iris/iris.data";
    using var client = new HttpClient();
    string csv = await client.GetStringAsync(url);

    var X = new List<double[]>();
    var y = new List<int>();

    foreach (var line in csv.Split('\n'))
    {
        var parts = line.Trim().Split(',');
        if (parts.Length < 5) continue;

        string label = parts[4];
        if (label != "Iris-setosa" && label != "Iris-versicolor") continue;

        X.Add([double.Parse(parts[0]), double.Parse(parts[2])]);
        y.Add(label == "Iris-setosa" ? 0 : 1);
    }

    return (X.ToArray(), y.ToArray());
}

public class Perceptron(double eta = 0.01, int epochs = 50, int randomState = 1)
{
    public double[] Weights { get; private set; } = [];
    public double Bias { get; private set; }
    public List<int> ErrorsPerEpoch { get; private set; } = [];

    public Perceptron Fit(double[][] X, int[] y)
    {
        var rng = new Random(randomState);
        Weights = new double[X[0].Length];
        for (int i = 0; i < Weights.Length; i++)
            Weights[i] = NextGaussian(rng, mean: 0.0, stdDev: 0.01);

        Bias = 0.0;
        ErrorsPerEpoch = [];

        for (int _ = 0; _ < epochs; _++)
        {
            int errors = 0;
            for (int i = 0; i < X.Length; i++)
            {
                double update = eta * (y[i] - Predict(X[i]));
                for (int j = 0; j < Weights.Length; j++)
                    Weights[j] += update * X[i][j];
                Bias += update;
                if (update != 0.0) errors++;
            }
            ErrorsPerEpoch.Add(errors);
        }
        return this;
    }

    public double NetInput(double[] X)
    {
        double result = Bias;
        for (int i = 0; i < Weights.Length; i++)
            result += X[i] * Weights[i];
        return result;
    }

    public int Predict(double[] X) => NetInput(X) >= 0.0 ? 1 : 0;

    private static double NextGaussian(Random rng, double mean, double stdDev)
    {
        double u1 = 1.0 - rng.NextDouble();
        double u2 = 1.0 - rng.NextDouble();
        double z = Math.Sqrt(-2.0 * Math.Log(u1)) * Math.Sin(2.0 * Math.PI * u2);
        return mean + stdDev * z;
    }
}

Explore SharpLsp

SharpLsp is a modern language server built on a three-tier architecture with a Rust host for ultra-fast syntax parsing and .NET sidecars for rich semantic analysis. It supports C# and F# with features like completions, diagnostics, refactoring, semantic tokens, and project system integration. Check out the link below to try it out!!

https://sharplsp.dev/docs

The post Building a Perceptron in .NET appeared first on Swacblooms🦋.

In Part 3, you learned how to interact with the page using actions like click(), fill(), and check(). Now you need to prove those actions produced the right result.

That is where assertions come in.

An assertion is a check that confirms something is true. In Playwright, assertions are built on expect() and are designed for the web. Instead of checking once and failing immediately, they retry for a short period while the UI catches up.

This is one of the biggest reasons Playwright tests are reliable.

The expect() API at a Glance

You already saw this pattern:

await expect(page).toHaveTitle(/Playwright/);

The structure is always the same:

await expect(target).matcher(value)

• target is what you are asserting on (page, a locator, a response, etc.)
• matcher is the condition (toBeVisible, toHaveText, toHaveURL, …)
• value is the expected value when required

For UI tests, your most common target is a locator:

await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();

Web-First Assertions (Auto-Retry by Default)

Playwright assertions are web-first. That means they keep re-checking until either:

1. The assertion passes, or
2. The assertion timeout is reached

So this:

await expect(page.getByText('Saved')).toBeVisible();

does not mean “check once right now.” It means “wait for this to become visible within the assertion timeout.”

Note: auto-retry applies to Playwright’s async web matchers (like toBeVisible and toHaveText). Generic value matchers such as expect(value).toBe(...) do not auto-retry.

By default, Playwright uses a 5 second assertion timeout unless you configure it.

You can override per assertion:

await expect(page.getByText('Saved')).toBeVisible({ timeout: 10_000 });

or globally in config:

// playwright.config.js
export default defineConfig({
  expect: {
    timeout: 10_000,
  },
});

Core Assertions You Will Use Most

toHaveTitle()

Asserts the page title.

await expect(page).toHaveTitle('Settings');
await expect(page).toHaveTitle(/Settings/);

toHaveURL()

Asserts the current URL.

await expect(page).toHaveURL('https://example.com/dashboard');
await expect(page).toHaveURL(/\/dashboard$/);

toBeVisible()

Checks that an element is visible to the user.

await expect(page.getByRole('alert')).toBeVisible();

toHaveText()

Checks exact or regex text content.

await expect(page.getByTestId('status')).toHaveText('Saved');
await expect(page.getByTestId('status')).toHaveText(/saved/i);

toBeEnabled()

Checks that an element is enabled and can be interacted with.

await expect(page.getByRole('button', { name: 'Submit' })).toBeEnabled();

A Realistic End-to-End Example

import { test, expect } from '@playwright/test';

test('user can save profile changes', async ({ page }) => {
  await page.goto('/profile');

  await page.getByLabel('Display name').fill('swacblooms');
  await page.getByRole('button', { name: 'Save changes' }).click();

  await expect(page).toHaveURL(/\/profile$/);
  await expect(page.getByRole('status')).toHaveText('Changes saved');
  await expect(page.getByRole('button', { name: 'Save changes' })).toBeEnabled();
});

Notice there are no manual sleeps. Assertions do the waiting.

Negative Assertions

You can assert that something is not true using .not:

await expect(page.getByText('Loading...')).not.toBeVisible();
await expect(page.getByRole('button', { name: 'Delete' })).not.toBeEnabled();

Use negative assertions carefully. They are useful, but positive checks are often clearer when possible.

Soft Assertions

A regular assertion fails the test immediately. A soft assertion records the failure and allows the test to continue.

await expect.soft(page.getByTestId('first-name')).toHaveValue('Ada');
await expect.soft(page.getByTestId('last-name')).toHaveValue('Lovelace');
await expect.soft(page.getByTestId('email')).toHaveValue('ada@example.com');

// test continues even if one soft check fails
await page.getByRole('button', { name: 'Continue' }).click();

Soft assertions are useful when you want to collect multiple mismatches in one run, for example in long forms or summary pages.

Use them intentionally. For critical checks, prefer normal assertions so failures stop immediately.

Polling for Non-UI Conditions

Sometimes you need to verify something that is not a locator state, such as a value that changes over time.

Use expect.poll():

await expect
  .poll(async () => {
    const response = await page.request.get('https://example.com/api/jobs/123');
    const data = await response.json();
    return data.status;
  })
  .toBe('completed');

Playwright keeps polling until the value becomes 'completed' or times out.

This gives you retry behavior for computed values, API state, and other async conditions.

Common Mistakes to Avoid

1. Using manual sleeps instead of assertions

// avoid
await page.waitForTimeout(2000);

// prefer
await expect(page.getByText('Saved')).toBeVisible();

2. Asserting raw values too early

// fragile
const text = await page.getByTestId('status').textContent();
expect(text).toBe('Saved');

Prefer Playwright locator assertions because they auto-retry:

await expect(page.getByTestId('status')).toHaveText('Saved');

3. Overusing soft assertions

If everything is soft, failures can be easy to miss. Keep core checks hard.

Under the Hood: Why Retry-ability Matters

Modern UIs are asynchronous.

• React/Vue/Angular re-render after network calls
• buttons enable after validation
• toast messages appear after state updates

If assertions checked only once, tests would be flaky.

Playwright’s retry model aligns your checks with real browser timing. Instead of adding arbitrary sleeps, you describe the desired end state and let Playwright wait for it.

That is the foundation of stable E2E tests.

What’s Next

In Part 5 you will learn playwright.config.js in depth. You will configure retries, workers, projects, baseURL, traces, screenshots, and other settings that shape how your whole suite runs locally and in CI.

The post Part 4 — Assertions: Verifying What You See appeared first on Swacblooms🦋.

In Part 2 you learned how to find elements on the page. In this article, you will put those locators to work by performing actions on them — clicking, typing, hovering, selecting, uploading files, and more.

You will also learn one of Playwright’s most important features: auto-waiting. Playwright does not blindly fire an action the moment you call it. It waits until the element is ready. This is why Playwright tests are far less flaky than tests written with older tools.

Auto-Waiting — Why You Rarely Need waitFor

Before covering individual actions, it is worth understanding what happens under the hood every time you call one.

When you write:

await page.getByRole('button', { name: 'Submit' }).click();

Playwright does not just fire a click immediately. It first checks that the element:

• Exists in the DOM
• Is visible (not hidden with display: none or visibility: hidden)
• Is stable (not animating or moving)
• Is enabled (not disabled)
• Is not obscured by another element

Only when all of those conditions are met does Playwright act. If the element is not ready yet, Playwright keeps retrying until the configured timeout is reached before failing.

This means you rarely need to write:

await page.waitForSelector('.submit-button'); // rarely needed
await page.waitForTimeout(2000);              // almost never needed

Just write the action. Playwright handles the waiting.

Clicking

click() is the most common action. It simulates a real mouse click — move, press, release.

// single click
await page.getByRole('button', { name: 'Submit' }).click();

// double click
await page.getByRole('button', { name: 'Edit' }).dblclick();

// right click (context menu)
await page.getByRole('listitem', { name: 'File' }).click({ button: 'right' });

// click a specific position within an element
await page.getByRole('canvas').click({ position: { x: 100, y: 200 } });

If the element is covered by an overlay like a cookie banner, Playwright will throw rather than silently clicking the wrong thing. Fix the root cause — dismiss the overlay first.

Typing and Filling Inputs

There are two ways to put text into an input: fill() and pressSequentially().

fill() — Use This First

fill() clears the current value and sets the new one in a single operation. It is fast and reliable.

await page.getByLabel('Email address').fill('user@example.com');
await page.getByLabel('Password').fill('secret123');

pressSequentially() — When You Need Key-by-Key Input

Some inputs respond to individual keystrokes — autocomplete dropdowns, for example. pressSequentially() types character by character, triggering keyboard events as it goes.

await page.getByLabel('Search').pressSequentially('play', { delay: 50 });

The delay option adds a pause between keystrokes in milliseconds. Without it the typing is instantaneous, which some inputs do not handle correctly.

clear() — Emptying a Field

await page.getByLabel('Username').clear();

press() — Single Key Presses

Use press() when you need to hit a specific key — Enter, Tab, Escape, or an arrow key.

await page.getByLabel('Search').press('Enter');
await page.getByRole('textbox').press('Tab');
await page.getByRole('dialog').press('Escape');

Key names follow the KeyboardEvent.key standard. Common ones:

Checkboxes and Radio Buttons

Use check() and uncheck() rather than click() for checkboxes and radio buttons. They are more explicit and Playwright verifies the resulting state.

// check a checkbox
await page.getByLabel('Remember me').check();

// uncheck it
await page.getByLabel('Remember me').uncheck();

// select a radio button
await page.getByLabel('Credit card').check();

To verify the current state:

await expect(page.getByLabel('Remember me')).toBeChecked();
await expect(page.getByLabel('Remember me')).not.toBeChecked();

Dropdowns — selectOption()

For a native <select> element, use selectOption().

// select by visible text
await page.getByLabel('Country').selectOption('United Kingdom');

// select by value attribute
await page.getByLabel('Country').selectOption({ value: 'uk' });

// select by index (zero-based)
await page.getByLabel('Country').selectOption({ index: 2 });

// select multiple options (if the select allows it)
await page.getByLabel('Interests').selectOption(['Music', 'Sport']);

Hovering

hover() moves the mouse over an element without clicking. Use it to trigger tooltips, reveal dropdown menus, or test hover states.

await page.getByRole('button', { name: 'More options' }).hover();

Focus and Blur

// move keyboard focus to an element
await page.getByLabel('Email').focus();

// remove focus
await page.getByLabel('Email').blur();

File Uploads

setInputFiles() sets files on an <input type="file"> element.

// upload a single file
await page.getByLabel('Upload document').setInputFiles('path/to/file.pdf');

// upload multiple files
await page.getByLabel('Upload photos').setInputFiles([
  'photo1.jpg',
  'photo2.jpg',
]);

// clear a previously selected file
await page.getByLabel('Upload document').setInputFiles([]);

For upload dialogs triggered by a button rather than a direct file input:

const [fileChooser] = await Promise.all([
  page.waitForEvent('filechooser'),
  page.getByRole('button', { name: 'Upload' }).click(),
]);
await fileChooser.setFiles('path/to/file.pdf');

Drag and Drop

await page.getByRole('listitem', { name: 'Task A' }).dragTo(
  page.getByRole('region', { name: 'Done' })
);

For fine-grained control:

await page.getByRole('slider').dragTo(
  page.getByRole('slider'),
  { targetPosition: { x: 200, y: 0 } }
);

Scrolling

Playwright scrolls automatically when it needs to bring an element into view before acting. For explicit scrolling:

// scroll an element into view
await page.getByRole('heading', { name: 'Pricing' }).scrollIntoViewIfNeeded();

// scroll the page by a pixel amount
await page.mouse.wheel(0, 500);

Summary

In Part 3, you learned how to interact with the page in a reliable way.

• Playwright waits for elements to be ready before it performs an action.
• fill() is the default choice for text inputs, while pressSequentially() is useful when key-by-key typing is required.
• check() and uncheck() are the right tools for checkboxes and radio buttons.
• selectOption() is used for native <select> dropdowns.
• press() lets you send single keys and key combinations such as Control+a.
• setInputFiles() works for file inputs, and the filechooser event pattern works for upload buttons.
• In most tests, you can skip manual waits like waitForTimeout.

What’s Next

In Part 4 you will learn assertions — how to verify that the right things appear on the page after your actions. Playwright’s web-first assertions retry automatically, and you will learn why that matters and how to use them correctly.

The post Part 3 — Actions and Auto-Waiting: Putting Locators to Work appeared first on Swacblooms🦋.

Before you can click a button, fill a form, or assert that something is visible, you need to tell Playwright which element you are talking about. That is what locators are for.

A locator is not just a selector — it is a smart reference to an element that re-queries the DOM every time you use it. This means if the page re-renders between steps, Playwright finds the fresh element automatically rather than holding a stale reference that no longer exists.

In this article, you will learn some of the most common locator methods Playwright provides, when to use each one, and the priority order the Playwright team recommends.

Recommended Built-in Locators

Playwright’s docs recommend these built-in locators over CSS and XPath because they are tied to what users actually see and interact with:

1. getByRole
2. getByText
3. getByLabel
4. getByPlaceholder
5. getByAltText
6. getByTitle
7. getByTestId

The guiding principle: the closer a locator is to how a real user perceives the page, the better. Users read text and interact with buttons and links — they do not think in CSS class names.

getByRole — Start Here

getByRole finds elements by their ARIA role and accessible name. This is the recommended first choice for almost every interactive element on the page.

// finds <a href="/docs/intro">Get started</a>
page.getByRole('link', { name: 'Get started' })

// finds <button>Submit</button>
page.getByRole('button', { name: 'Submit' })

// finds <h1>Installation</h1>
page.getByRole('heading', { name: 'Installation' })

// finds <input type="checkbox"> with label "Remember me"
page.getByRole('checkbox', { name: 'Remember me' })

The role comes from the HTML element itself — no aria-* attributes needed. The browser assigns roles automatically:

The accessible name comes from the element’s visible text content (as you saw in Part 1 with the Get started link). If the element has an aria-label or aria-labelledby, that takes priority over text content.

The name option accepts a string or a regular expression:

// exact string match
page.getByRole('button', { name: 'Sign in' })

// regex — useful when the text is dynamic
page.getByRole('button', { name: /sign in/i })

getByText — For Non-Interactive Elements

Use getByText when you want to find an element by its visible text content and there is no meaningful role to target — typically a <div>, <span>, or <p>.

// finds any element containing the text "Welcome back"
page.getByText('Welcome back')

// exact match only
page.getByText('Welcome back', { exact: true })

// regex
page.getByText(/welcome back/i)

Important: Playwright normalises whitespace automatically, even with { exact: true }. Multiple spaces become one, line breaks become spaces, and leading/trailing whitespace is ignored.

Avoid using getByText on buttons and links — use getByRole for those. getByText is for reading content, not for triggering actions.

getByLabel — For Form Fields

getByLabel finds an input by the text of its associated <label>. This is the right tool any time you are filling in a form.

// finds the input associated with <label>Email address</label>
page.getByLabel('Email address')

// usage in a test
await page.getByLabel('Email address').fill('user@example.com');
await page.getByLabel('Password').fill('secret');

The label association can be done two ways in HTML, and getByLabel handles both:

<!-- wrapping label -->
<label>
  Email address
  <input type="email" />
</label>

<!-- linked by for/id -->
<label for="email">Email address</label>
<input id="email" type="email" />

getByPlaceholder — When There Is No Label

Some inputs skip a visible label and rely on placeholder text instead. Use getByPlaceholder for those.

<input type="email" placeholder="Enter your email" />

await page.getByPlaceholder('Enter your email').fill('user@example.com');

Prefer getByLabel over getByPlaceholder when both are available — a visible label is better for accessibility and more stable as a test target.

getByAltText — For Images

getByAltText finds elements by their alt attribute. In practice this means images.

<img src="logo.png" alt="Company logo" />

await expect(page.getByAltText('Company logo')).toBeVisible();

getByTitle — For Title Attributes

getByTitle matches elements with a title attribute. Less common, but useful for icon buttons and tooltips that carry no visible text.

<button title="Close dialog">✕</button>

await page.getByTitle('Close dialog').click();

getByTestId — The Explicit Contract

getByTestId finds elements by a data-testid attribute (or a custom attribute you configure).

<button data-testid="submit-order">Place order</button>

await page.getByTestId('submit-order').click();

This locator is the most resilient to UI changes — the visible text and styling can change entirely without breaking your test. The trade-off: it requires you to add data-testid attributes to your HTML, and it is not based on anything a real user perceives.

Use it when:

• A role or text locator is not specific enough
• You want an explicit, stable contract between your tests and a specific element
• The element has no accessible role or visible text

You can configure a custom attribute name in playwright.config.js:

use: {
  testIdAttribute: 'data-cy', // use data-cy instead of data-testid
}

CSS and XPath — Last Resort

When none of the above fit, you can fall back to CSS selectors or XPath via locator().

// ID selector
page.locator('#submit-button')

// CSS selector
page.locator('.nav-menu > li:first-child')

// XPath
page.locator('//button[@type="submit"]')

Playwright auto-detects whether you passed CSS or XPath — no prefix needed.

Why avoid these? The DOM changes. Class names get renamed, elements get restructured, and your tests break for reasons unrelated to the actual behaviour of the app. The role and text-based locators are far more stable because they are tied to what users see, not to implementation details.

One additional limitation: XPath does not pierce Shadow DOM. All other Playwright locators work inside shadow roots by default.

Filtering Locators

When a locator matches more than one element, use filter() to narrow it down.

// all list items that contain the text "In stock"
page.getByRole('listitem').filter({ hasText: 'In stock' })

// list items that do NOT contain "Sold out"
page.getByRole('listitem').filter({ hasNotText: 'Sold out' })

// list items that contain a child button labelled "Add to cart"
page.getByRole('listitem').filter({
  has: page.getByRole('button', { name: 'Add to cart' })
})

Chaining Locators

All locator methods are also available on a locator itself, so you can scope a search inside a specific part of the page.

// find the navigation section first, then look for a link inside it
page.getByRole('navigation').getByRole('link', { name: 'Pricing' })

// find a form, then find the submit button inside it
page.getByRole('form', { name: 'Checkout' }).getByRole('button', { name: 'Place order' })

This is cleaner and more precise than a deeply nested CSS selector, and it reads like plain English.

Strictness — One Element at a Time

Playwright locators are strict by default. If a locator matches more than one element and you call an action on it (like .click()), Playwright throws an error rather than silently picking the first match.

Error: locator.click: Error: strict mode violation:
getByRole('button', { name: 'Submit' }) resolved to 2 elements

This is intentional — it forces you to write specific locators. The fix is to make the locator more precise rather than reaching for .first() or .nth(0):

// vague — which Submit button?
page.getByRole('button', { name: 'Submit' })

// specific — scoped to the checkout form
page.getByRole('form', { name: 'Checkout' }).getByRole('button', { name: 'Submit' })

Summary

Here is what you learned in Part 2:

• A locator re-queries the DOM every time it is used — no stale element references
• Use getByRole first: it targets elements the same way users and screen readers do
• Use getByLabel for form inputs, getByText for static content, getByAltText for images
• Use getByTestId when you need an explicit, stable testing contract
• Avoid CSS and XPath unless nothing else fits — they are tied to implementation details
• filter() and chaining let you narrow down locators precisely
• Locators are strict: if more than one element matches, Playwright errors rather than guessing

What’s Next

In Part 3 we put locators to work. You will learn some of the actions Playwright can perform — clicking, typing, hovering, selecting, uploading files — and how Playwright’s auto-waiting means you almost never need to add a manual wait.

The post Part 2 — Understanding Locators: Finding Things on the Page appeared first on Swacblooms🦋.

If you have ever shipped a feature that looked perfect in your local browser but broke immediately in production, you already understand why automated browser testing exists. Playwright is the answer to the question: “How do we make that kind of testing fast, reliable, and not painful to write?”

This first article walks you through what Playwright is, why it stands out from its competitors, how to install it, and how to read your very first test. By the end, you will have a working setup and a solid mental model of what each piece does.

What Is Playwright?

Playwright is an open-source end-to-end (E2E) testing framework built by Microsoft. “End-to-end” means it controls a real browser — Chrome, Firefox, or Safari — the same way a real user would: clicking links, filling forms, navigating pages, and checking that the right content appears.

Unlike unit tests (which test isolated functions) or integration tests (which test modules together), E2E tests validate the entire stack from the UI down to the database and back. They are the closest thing to “a human actually using your app.”

Playwright supports:

• Chromium (Chrome / Edge)
• Firefox
• WebKit (Safari)
• Mobile viewports
• Multiple languages: JavaScript, TypeScript, Python, Java, .NET

This series uses JavaScript/TypeScript.

Why Playwright?

There are other browser automation tools out there — Selenium and Cypress being the most well-known. This series focuses on Playwright, and here is what makes it worth your time:

• Supports all three major browser engines — Chromium, Firefox, and WebKit — out of the box
• Auto-waits for elements to be ready before acting, so no manual sleeps or brittle waits
• Runs tests in parallel across browsers simultaneously
• First-class TypeScript support with no extra configuration
• Built-in network interception, trace recording, and a visual debugger
• Actively maintained by Microsoft with frequent releases

Installing Playwright

Playwright requires Node.js 20.x, 22.x, or 24.x. Check your version:

node --version

To scaffold a new Playwright project, run:

npm init playwright@latest

The CLI will ask a few questions:

• TypeScript or JavaScript? (choose either — this series uses both)
• Where to put your tests? (default: tests/)
• Add a GitHub Actions workflow? (yes — we cover this in Part 11)
• Install Playwright browsers? (yes)

That last step downloads Chromium, Firefox, and WebKit — about 300 MB total. Playwright ships its own browser binaries, so your system browsers never interfere.

After installation, your project looks like this:

your-project/
├── node_modules/
├── tests/
│   └── example.spec.js       ← your starter test
├── playwright.config.js      ← all configuration lives here
├── package.json
└── package-lock.json

Your First Test — Line by Line

Open tests/example.spec.js. Here is what it contains:

// @ts-check
import { test, expect } from '@playwright/test';

test('has title', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await expect(page).toHaveTitle(/Playwright/);
});

test('get started link', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await page.getByRole('link', { name: 'Get started' }).click();
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

Let’s break each part down.

// @ts-check

A JSDoc comment that tells VS Code to type-check this plain JavaScript file using TypeScript’s engine. You get autocomplete and inline errors without needing a tsconfig. Optional, but useful.

import { test, expect } from '@playwright/test'

Two things are imported:

• test — the function you use to define a test case (like it() in Jest)
• expect — the assertion library (like Jest’s expect, extended with browser-aware matchers)

test('has title', async ({ page }) => { ... })

• The first argument is the test name — what shows up in the report.
• The second argument is an async function that receives fixtures. The page fixture is Playwright’s central object: it represents a single browser tab.
• Every browser interaction is async, so you use await throughout.

await page.goto('https://playwright.dev/')

Navigates the browser to a URL. Playwright waits for the page to reach a “load” state before moving on.

await expect(page).toHaveTitle(/Playwright/)

Asserts that the page’s <title> tag matches the regular expression /Playwright/. This is a web-first assertion — if the title is not there yet, Playwright retries the check for up to 5 seconds before failing. No manual waits needed.

await page.getByRole('link', { name: 'Get started' }).click()

Finds an <a> element whose accessible name is “Get started” and clicks it. getByRole is the preferred way to select elements — it mirrors how assistive technologies see your page and is far more resilient than CSS selectors.

await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible()

After clicking, the test navigates to the installation page. This assertion checks that a heading with the text “Installation” becomes visible. Again, Playwright retries this automatically.

Understanding the playwright.config.js File

The playwright.config.js file controls how your entire test suite runs. The default configuration sets up three test projects — one for each browser engine.

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: 'html',
  use: {
    trace: 'on-first-retry',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox',  use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit',   use: { ...devices['Desktop Safari'] } },
  ],
});

Key settings to know right now:

We will explore every option in detail in Part 5.

Running Your Tests

# Run the full suite across all browsers
npx playwright test

# Run only in one browser
npx playwright test --project=chromium

# Run a specific file
npx playwright test tests/example.spec.js

# Watch the browser open (headed mode)
npx playwright test --headed

# Open the interactive HTML report after a run
npx playwright show-report

# Open UI Mode — live debugging with a built-in browser and test explorer
npx playwright test --ui

When tests pass, you will see:

Running 6 tests using 3 workers
  6 passed (8.3s)

That “6 tests” comes from 2 test cases × 3 browser projects.

Reading a Failure

Break one of the assertions intentionally:

await expect(page).toHaveTitle(/NotARealTitle/);

Run again. Playwright will print:

Error: expect(page).toHaveTitle(expected)

Expected pattern: /NotARealTitle/
Received string:  "Fast and reliable end-to-end testing for modern web apps | Playwright"

The diff is clear and actionable. The HTML report adds a screenshot of the page at the moment of failure, and if tracing is enabled, a full step-by-step replay.

Summary

Here is what you learned in Part 1:

• Playwright is an E2E testing framework that drives real browsers
• It supports Chromium, Firefox, and WebKit with auto-waiting built in
• npm init playwright@latest scaffolds a working project in seconds
• A test is an async function that receives a page fixture
• expect() assertions are web-first: they retry until they pass or time out
• playwright.config.js controls browsers, parallelism, retries, and more
• npx playwright test runs everything; --project and --headed are useful flags

What’s Next

In Part 2, we dive deep into locators — the API you will use in every single test to find elements on the page. You will learn why getByRole is almost always the right choice, and when to reach for other strategies.

The post What Is Playwright and Why Should You Care? appeared first on Swacblooms🦋.

After implementing track toggling with replaceTrack(), a crucial question emerges: When do I need to renegotiate (create a new offer/answer) vs when can I just swap tracks?

Understanding this is critical for building efficient WebRTC applications. Unnecessary renegotiation adds latency and complexity, while missing required renegotiation breaks your connection.

Quick Answer

Use replaceTrack() (no renegotiation) when:

• Swapping tracks of the same type (camera 1 → camera 2)
• Toggling tracks on/off (video → null → video)
• The transceiver slot already exists

Renegotiate (new offer/answer) when:

• Adding new transceivers (new media types)
• Changing transceiver direction
• Stopping transceivers permanently
• Any structural SDP changes

What is a Transceiver?

A transceiver is a bidirectional media slot in your peer connection:

// Creates a slot for video communication
const transceiver = peerConnection.addTransceiver('video', {
  direction: 'sendrecv'  // Can send AND receive
})

// The transceiver has:
// - sender: sends your video to the peer
// - receiver: receives peer's video
// - direction: sendrecv, sendonly, recvonly, inactive

Key insight: Once a transceiver exists, you can swap tracks in/out without renegotiation. The slot is reserved for the connection lifetime.

The SDP Connection

Renegotiation is required when the SDP (Session Description Protocol) structure changes:

v=0
o=- 123456 2 IN IP4 127.0.0.1
s=-
t=0 0
m=video 9 UDP/TLS/RTP/SAVPF 96 97    ← Video m-line (transceiver slot)
m=audio 9 UDP/TLS/RTP/SAVPF 111      ← Audio m-line (transceiver slot)

• Each m= line represents a transceiver
• Adding/removing m-lines = renegotiation required
• Changing direction in m-line = renegotiation required
• Swapping tracks within existing m-line = NO renegotiation needed

Scenarios: No Renegotiation Needed

1. Camera Toggling (On → Off → On)

let videoSender: RTCRtpSender | null = null

// Initial setup: create transceiver
const videoTransceiver = peerA.addTransceiver(videoTrack, {
  direction: 'sendrecv',
  streams: [localStream]
})
videoSender = videoTransceiver.sender

// Later: Turn camera OFF
await videoSender.replaceTrack(null)  //  NO renegotiation

// Later: Turn camera ON
const newStream = await getUserMedia({ video: true })
const newTrack = newStream.getVideoTracks()[0]
await videoSender.replaceTrack(newTrack)  //  NO renegotiation

Why it works: The video transceiver slot exists. We’re just changing what goes into it (track → null → track).

2. Switching Cameras

// Front camera → Back camera
const constraints = { video: { facingMode: 'environment' } }
const newStream = await getUserMedia(constraints)
const newTrack = newStream.getVideoTracks()[0]

await videoSender.replaceTrack(newTrack)  //  NO renegotiation

Why it works: Same transceiver, different video source.

3. Switching Microphones

// Default mic → Headset mic
const constraints = { audio: { deviceId: headsetMicId } }
const newStream = await getUserMedia(constraints)
const newTrack = newStream.getAudioTracks()[0]

await audioSender.replaceTrack(newTrack)  //  NO renegotiation

Why it works: Same transceiver, different audio source.

4. Changing Video Resolution/Frame Rate

// 720p → 1080p
const constraints = {
  video: { width: 1920, height: 1080, frameRate: 30 }
}
const newStream = await getUserMedia(constraints)
const newTrack = newStream.getVideoTracks()[0]

await videoSender.replaceTrack(newTrack)  //  NO renegotiation

Why it works: Still using the same video transceiver.

Scenarios: Renegotiation Required

1. Adding Screen Sharing

// Initial: video + audio
const videoTransceiver = peerA.addTransceiver(videoTrack, {
  direction: 'sendrecv',
  streams: [localStream]
})
const audioTransceiver = peerA.addTransceiver(audioTrack, {
  direction: 'sendrecv',
  streams: [localStream]
})

// Create offer/answer...

// Later: Add screen sharing (NEW transceiver)
const screenStream = await navigator.mediaDevices.getDisplayMedia({
  video: true
})
const screenTrack = screenStream.getVideoTracks()[0]

// Adding a new transceiver
const screenTransceiver = peerA.addTransceiver(screenTrack, {
  direction: 'sendrecv',
  streams: [screenStream]
})

//  MUST renegotiate!
const offer = await peerA.createOffer()
await peerA.setLocalDescription(offer)

// Send offer to peer B
// Wait for answer from peer B
const answer = await receiveAnswerFromPeerB()
await peerA.setRemoteDescription(answer)

Why renegotiation is needed: We added a new m-line to the SDP. Peer B needs to know about this new media stream.

2. Changing Transceiver Direction

// Initial: bidirectional
const transceiver = peerA.addTransceiver('video', {
  direction: 'sendrecv'  // Can send AND receive
})

// Later: Make it send-only
transceiver.direction = 'sendonly'

// MUST renegotiate!
const offer = await peerA.createOffer()
await peerA.setLocalDescription(offer)
// ... complete negotiation

Why renegotiation is needed: The SDP m-line direction attribute changed. Peer B needs to update its expectations.

3. Stopping a Transceiver

const transceiver = peerA.getTransceivers()[0]

transceiver.stop()  // Permanently stops the transceiver

//  MUST renegotiate!
const offer = await peerA.createOffer()
await peerA.setLocalDescription(offer)
// ... complete negotiation

Why renegotiation is needed: The m-line is marked as inactive in SDP. This is a structural change.

Note: You rarely need to stop transceivers. Usually replaceTrack(null) is sufficient.

4. Adding Data Channels After Connection

// Initial connection with video/audio

// Later: Add data channel
const dataChannel = peerA.createDataChannel('fileTransfer')

//  MUST renegotiate!
const offer = await peerA.createOffer()
await peerA.setLocalDescription(offer)
// ... complete negotiation

Why renegotiation is needed: Data channels add application m-lines to SDP.

Performance Implications

replaceTrack() (No Renegotiation)

Performance:

• Near-instant (typically < 50ms)
• No network round-trip
• No SDP parsing
• Seamless for users

Use for:

• Real-time track toggling
• Device switching
• Quality changes

// Fast and seamless
console.time('replaceTrack')
await videoSender.replaceTrack(newTrack)
console.timeEnd('replaceTrack')  // ~10-30ms

Renegotiation (Offer/Answer)

Performance:

• Slow (typically 500ms – 2000ms)
• Multiple network round-trip
• SDP parsing on both sides
• Potential for brief disruption

Steps involved:

1. Create offer (100-200ms)
2. Set local description (50-100ms)
3. Send offer to peer (network latency)
4. Peer processes offer (50-100ms)
5. Peer creates answer (100-200ms)
6. Peer sets local description (50-100ms)
7. Answer sent back (network latency)
8. Set remote description (50-100ms)

// Slower due to network round trips
console.time('renegotiate')
const offer = await peerA.createOffer()
await peerA.setLocalDescription(offer)
await sendOfferToPeer(offer)
const answer = await waitForAnswer()
await peerA.setRemoteDescription(answer)
console.timeEnd('renegotiate')  // ~500-2000ms

Decision Tree

Do you need to add a NEW type of media?
├─ YES → Renegotiate (add transceiver, then offer/answer)
└─ NO
   │
   Do you need to change transceiver direction?
   ├─ YES → Renegotiate (change direction, then offer/answer)
   └─ NO
      │
      Do you need to permanently stop a transceiver?
      ├─ YES → Renegotiate (stop transceiver, then offer/answer)
      └─ NO
         │
         Just changing/toggling existing track?
         └─ YES → Use replaceTrack() 

Summary

The Golden Rule: If the transceiver slot exists, use replaceTrack(). If you need a new slot (or to modify slot properties), renegotiate.

The post WebRTC Renegotiation: When You Need It and When You Don’t appeared first on Swacblooms🦋.

Here’s how I configured it.

Garage Bucket-to-Website

Garage doesn’t currently support anonymous S3 access, so I used the bucket-to-website feature for public file access. This works by:

1. Setting the bucket name to match my public domain (e.g., cdn.myapp.com)

2. Enabling website mode via the Garage web UI

3. Pointing my DNS to Garage’s web endpoint

4. Uploading files via S3 API

5. Accessing files directly via public HTTP URLs on my domain

This provides persistent public access without pre-signed URLs – perfect for truly public assets like logos.

Environment Variables

Before (Cloudflare R2):

CLOUDFLARE_R2_ENDPOINT

CLOUDFLARE_R2_ACCESS_KEY_ID

CLOUDFLARE_R2_SECRET_ACCESS_KEY

CLOUDFLARE_R2_BUCKET_NAME

After (Garage):

GARAGE_S3_ENDPOINT=https://cdn.myapp.com # Public web endpoint (matches bucket name)

GARAGE_S3_API_ENDPOINT=https://s3-api.myapp.com # S3 API endpoint (optional)

GARAGE_S3_ACCESS_KEY_ID=your_key_id

GARAGE_S3_SECRET_ACCESS_KEY=your_secret

GARAGE_S3_BUCKET_NAME=cdn.myapp.com # Must match public domain for website mode

Important: The bucket name must match your public domain for bucket-to-website to work.

S3 Client Configuration

The critical configuration for Garage compatibility:

var config = new AmazonS3Config

{

   ServiceURL = apiServiceUrl, // Garage S3 API endpoint

   ForcePathStyle = true, // Required for Garage

   AuthenticationRegion = "garage"

};

var s3Client = new AmazonS3Client(accessKeyId, secretAccessKey, config);

Key points:

– ForcePathStyle = true is required for Garage

– AuthenticationRegion = “garage” This is particularly important for non-AWS S3-compatible services like Garage that use custom region naming

– Separate API endpoint for uploads vs. public website endpoint for downloads

Upload Implementation

public async Task<string> UploadImageAsync(Stream fileStream, string fileName)

{

   var uniqueFileName = $"logos/{Guid.NewGuid()}{Path.GetExtension(fileName)}";

   var putRequest = new PutObjectRequest

   {

      BucketName = _bucketName,

      Key = uniqueFileName,

      InputStream = fileStream,

      ContentType = contentType,

      UseChunkEncoding = false // Important for compatibility

   };

   await _s3Client.PutObjectAsync(putRequest);

   // Return public website URL

   return $"{_publicEndpoint}/{uniqueFileName}";

}

The returned URL (https://cdn.myapp.com/logos/abc123.png) is directly accessible – no auth needed.

Migrating Existing Assets

I used a simple script to transfer existing files from R2 to Garage. The script downloaded files from R2 and re-uploaded them to Garage using the S3 API, preserving the same file paths for zero downtime.

Key Takeaways

Critical configuration:

– ForcePathStyle = true and AuthenticationRegion = “garage” are essential

– UseChunkEncoding = false prevents upload issues

– Bucket name must match your public domain for website mode

– DNS must point to Garage’s web endpoint

Why bucket-to-website:

– Garage doesn’t support anonymous S3 access yet

– Provides persistent public access without pre-signed URLs

– Perfect for truly public assets (logos, images, etc.)

Why Garage:

– Fixed costs instead of variable API/bandwidth charges

– Full control over storage infrastructure

– S3 is compatible with minimal code changes

For side projects where cost predictability matters, Garage is excellent. Self-hosting means I know exactly what I’m paying each month.

—

Resources:

– Garage Documentation

– AWSSDK.S3 NuGet Package

The post Migrating from Cloudflare R2 to Garage in .NET appeared first on Swacblooms🦋.