Home / User Guide / Run URL Tests

How To Check Redirects using URL Mapping Rules?

HEADMasterSEO is a bulk redirect checker that allows you to automatically test if your redirections are setup correctly. It can:

• Check 301 redirections. Are your redirects returning the correct HTTP redirection status code?
• Check your redirects for redirect chains and redirect loops.
• Run tests that automatically check if every URL redirects to the correct destination URL using a single 301 redirect.

You don't need to examine where every URL redirection goes. HEADMasterSEO can automatically grade every URL redirection (PASS/FAIL) for correctness if you supply it with URL mapping rules.

You can immediately see which links are incorrectly redirected!

The concept is simple:

• You write URL mapping rules once in a text file.
• These mapping rules tell HEADMasterSEO where every URL needs to be redirected to.
• You then check all redirects by running HEADMasterSEO tests, which automatically grade every link with a PASS or FAIL score (so you don't need to audit every status code and redirection type and location manually).

You write the URL mapping rules once and run the redirection tests as many times as needed to fix all redirection errors.

Here's how the process works:

1.  Prepare a list of URL redirect mapping rules. They can be simple plain text rules, regular expression rules or a simple form of {} syntax for non-technical users (see below for documentation). Each rule can match thousands of links such as sections, blog posts, forum posts, product categories
2.  Import a list of your old URLs that need to be tested
3.  Optionally, rewrite the URLs to your staging environment (see URL Rewriting)
4.  Use fast HEAD requests (or optionally GET ones) and follow redirects of your links
5.  Automatically check if your old URLs redirect properly to the correct new URLs
6.  Results are PASS/FAIL and reasons for failure. You can export results to CSV using the Standard Report

Running A Redirection Test

Open the "Test URLs" menu > "Test URL Mappings" screen.

Set the input file with your test URLs and the text file with all mapping rules (see below) and start the test.

An input URL will get a PASS grade if:

• There is a mapping rule that matches it
• The tested URL redirects to the correct destination URL with a single 301 redirect

Reasons for getting a FAIL grade:

• Mapping rules file has no rule that matches the input URL
• URL does not redirect to the correct destination URL
• The correct destination URL does not return status code 200
• URL does not redirect at all
• Redirect Chains
• Non-301 Redirect (such as 302 redirect)
• Redirect Loops
• Max redirects exceeded (10)
• Any other failure such as SSL errors

Note: If you have an invalid SSL certificate on the staging server then configure HEADMasterSEO to ignore SSL errors (SSL/TLS configuration screen). If you don't set the option, the program will fail all URLs due to "SSL errors".

Mapping Rules File Format

The mapping rules file tells HEADMasterSEO where an input URL should redirect to.

It is a simple plain text file. Comments start with the ; symbol. General format is:

mapFromURL mapToURL

Redirect Rules Format

There are 3 formats for specifying redirection rules:

1. Plain URL rule
2. Simple {} rule
3. Regular expression rule

Sample mapping rules file:

; this is a comment
; simple plain mapping rule
http://olddomain.com http://newdomain.com
; simple {} rule
/blog/{} /blogs/{1}
; reg expression rule
(/forum/([a-zA-Z0-9]+)/(.+)) http://discussions.newdomain.com/{1}/{2}

The plain URL rule

The simplest rule format is: sourceURL destinationURL. You can use full urls like: http://www.domain.com/path or you can use relative paths such as /blog.

Once you use a full url, you can then use relative paths (always starting with /) in the following rules. Use another full URL to change the source or destination domain.

You can use full/relative paths for both the source (mapFrom) and destination (mapTo) URLs.

Example:

;redirect old domain to new one
http://www.olddomain.com http://newdomain.com
; use relative paths now
/about /about-us
/contact /contact
; change the destination domain to a subdomain
/forum http://forums.newdomain.com
; change back the destination domain
/support http://newdomain.com/support

In this example, the 4th line tells HEADMasterSEO that http://www.olddomain.com/about should redirect to http://newdomain.com/about-us

The simple {} rule

The mapFrom (first URL in a pair) can contain {}. These {} will match any character until the program finds the character after the {} or the URL ends.

Example: /blog/{}/ will match /blog/hello/ and /blog/category/, but it will not match /blog/just-this or /blog/category/post/

The mapTo (the 2nd URL in a pair) can contain {1}, {2} etc. and these will be replaced by the matched text from the input URL {}.

Example rule:

/blog/{}/{} /blog/{2}

If your input link is /blog/category/blog-title, the program will check if it redirects to /blog/blog-title

Here we effectively remove the category from the input links.

Important

Every input link is matched to just one mapping rule. If a link can be matched to more than 1 rule, HEADMasterSEO picks the 1st rule in the file as the correct rule.

The input link: /forum/subforum/forum-post can match both these rules

/forum/{} /dest1
/forum/{}/{} /dest2

If both rules are in the mapping rules file, HEADMasterSEO will match the input to the 1st rule in the file (/forum/{} /dest1).

The regular expression mapping rule

Regular expression rules always enclose the mapFrom URL in () brackets. The 2nd URL is rewritten again using {1}{2}... matches from the input URL. The {1} corresponds to the 2nd matching group, {2} to the 3rd etc.

Example:

(/forum/([a-zA-Z0-9]+)/(.+)) http://discussions.newdomain.com/{1}/{2}

If the input URL is /forum/headmasterseo/help, HEADMasterSEO will test if it redirects to http://discussions.newdomain.com/headmasterseo/help

Here {1} will be equal to "headmasterseo" and {2} will be equal to "help".

NOTE: use regular expression rules only with relative paths. Domain matching is not supported!

How to ignore parts of the destination URLs?

Sometimes you need to ignore parts of the destination URLs. An example would the server adding session IDs.

To make the URL testing work, you need to tell HEADMasterSEO to ignore the session IDs in the destination URLs or all tests with fail with "Bad final URL" error.

You do that by using the {} syntax in the destination URL. The {} will ignore one or more characters until the program finds the character after the {} or the URL ends.

Example: let's say the server adds a sid parameter at the end of the URLs such as: http://yourserver.com/page-url?sid=somevalue

The following rule would ignore the sid parameter:

\page-url \page-url?sid{}

You can mix the {number} replacements and the {} "ignore parts in the destination URLs":

/blog/{}/{} /blog/{2}?sid{}

If you need help writing your mapping rules file or need consulting on a website migration, then contact us.