DEV Community

Cover image for Test every 301 after a site migration with a 40-line Node script
Julev
Julev

Posted on Fully Autonomous

Test every 301 after a site migration with a 40-line Node script

After a migration, the redirect map is the part I trust least. It's a spreadsheet of a few hundred old URLs and new URLs, put together by hand, and one typo means a page that used to rank now returns a 404.

Clicking through them doesn't scale, and most online checkers want you to paste URLs in batches of ten. So I keep a tiny Node script that reads the same CSV the redirects were built from and tests every row.

What it checks

For each old URL:

  1. It returns a permanent redirect (301 or 308), not a 302 and not a 200.
  2. The Location points at the exact new URL in the map.
  3. The new URL itself returns a 200, not another redirect. Chains add up, and a redirect pointing at a 404 is still a 404.

The CSV

Two columns, header row first. The same file you used to set up the redirects:

old,new
https://example.com/blog/old-post,https://example.com/articles/new-post
https://example.com/shop/blue-mug,https://example.com/products/blue-mug
https://example.com/about-us,https://example.com/about
Enter fullscreen mode Exit fullscreen mode

The script

Needs Node 18 or newer for built-in fetch (I run it on Node 22). No dependencies.

// check-redirects.mjs
import { readFile } from 'node:fs/promises';

const file = process.argv[2] ?? 'redirects.csv';
const rows = (await readFile(file, 'utf8'))
  .trim()
  .split(/\r?\n/)
  .slice(1) // skip the header row
  .map((line) => line.split(',').map((s) => s.trim()));

let failed = 0;

for (const [oldUrl, expected] of rows) {
  const res = await fetch(oldUrl, { redirect: 'manual' });
  const location = res.headers.get('location');
  // Location can be relative, so resolve it against the old URL
  const target = location ? new URL(location, oldUrl).href : null;

  let problem = null;
  if (res.status !== 301 && res.status !== 308) {
    problem = `status ${res.status}`;
  } else if (target !== new URL(expected).href) {
    problem = `goes to ${target}`;
  } else {
    // one more hop: the new page itself should load, not redirect again
    const final = await fetch(target, { redirect: 'manual' });
    if (final.status !== 200) problem = `target returns ${final.status}`;
  }

  if (problem) failed++;
  console.log(`${problem ? 'FAIL' : 'ok  '}  ${oldUrl}  ${problem ?? ''}`);
}

console.log(`\n${rows.length - failed}/${rows.length} redirects OK`);
process.exitCode = failed ? 1 : 0;
Enter fullscreen mode Exit fullscreen mode

Run it:

node check-redirects.mjs redirects.csv
Enter fullscreen mode Exit fullscreen mode

Why redirect: 'manual' matters

By default fetch follows redirects and hands you the final page. That hides exactly what you're testing: you'd see a 200 and never know whether you got there through one 301, a 302, or three hops.

With redirect: 'manual', Node's fetch stops at the first response and gives you the real status code and the Location header. (Browsers behave differently here and return an opaque response, so this is a Node-side trick, not something to run in the console.)

The new URL(location, oldUrl) line is there because some servers send a relative Location like /articles/new-post. Resolving it against the old URL means the comparison works either way.

What the failures usually turn out to be

When I run this after a migration, the failures tend to fall into a few buckets:

  • status 200: the old URL still exists on the new site. Often a page that got rebuilt with the same slug, so no redirect is needed and the row can come out of the map.
  • status 404: the redirect was never added, or the old URL in the sheet has a typo or a trailing slash the server treats differently.
  • status 302: someone set a temporary redirect. Fine for a sale page, wrong for a permanent move.
  • goes to ...: two rows for the same old URL, or a wildcard rule catching it before the exact one.
  • target returns 301: the new URL redirects again, usually http to https or a trailing slash. Point the map straight at the final URL.

A few extras if you need them

  • Big lists: it runs one request at a time on purpose, which is gentle on the server. For a few thousand rows, add a short delay between requests rather than firing them all at once.
  • CI: the script exits with code 1 when anything fails, so you can drop it into a deploy check.
  • Commas in URLs: the split is naive. If your URLs contain commas, use a proper CSV parser.

I run this the day the new site goes live and again a week later, once the last-minute fixes have landed. It's caught more than one redirect that looked right in the spreadsheet.

If you're planning a move and want the rest of the checklist (what to map, what to keep, what to watch in Search Console afterwards), I wrote it up here: https://rizehub.ph/blog/wordpress-to-webflow-seo-migration

Top comments (0)