Note: In the links throughout this documentation, we use the internationalized domain name
domaintest.みんな. In links, GitHub improperly encodes this as
domaintest.%E3%81%BF%E3%82%93%E3%81%AA. Domain names should not be URL-encoded. (This is exactly the type of issue that the Domain Test tool is intended to catch.)
This bug breaks the hyperlinks in this documentation for users of Firefox, Internet Explorer, and Safari; we've reported the issue to GitHub. In the meantime, affected users can test the examples by copying and pasting the on-screen text.
Domain Test is a tool designed to help developers test their applications for compatibility with new top-level domains (TLDs). Developed by Google and launched in a partnership between Google Registry and Ausregistry, CentralNic, Donuts, RightSide, and Uniregistry, Domain Test is an open source project available under the Apache 2 license and can be used across 145 new TLDs. It is freely available for use and modification.
In 2011, the Internet Committee for Assigned Names and Numbers (ICANN) approved a new gTLD program, where applicants could apply to own and operate new gTLDs. A total of 1,930 applications were filed, and beginning in 2013, ICANN began delegating new gTLDs to the root DNS zone. These gTLDs have a series of characteristics, such as string length and the use of non-Latin scripts, that can cause bugs in software. Domain Test helps developers identify and fix these problems.
This repository contains the documentation and code for Domain Test. For clarity, the documentation uses the term “new TLDs” to refer to the universe of new generic top-level domains (gTLDs), new country-code top-level domains (ccTLDs), and internationalized domain names (IDNs).
The Domain Test service runs on AppEngine and is available for any developer to use. The syntax examples in this documentation use the
domaintest.みんな domain name. However, depending on what type of new TLD you want to test, you can substitute any of the strings in the Domain Test TLDs section of this documentation.
HTTP Testing API
You can use the HTTP Testing API to construct an HTTP GET or POST request that results in a predictable server response. By observing your application's handling of the server’s response, you can determine whether the application making the HTTP call works properly with new TLDs.
GET requests should use the following syntax:
POST requests can mix parameters between the query string, like GET, and the POST body. Both
application/x-www-form-urlencoded are supported, and the
postpayload parameter does not interpret the POST body at all.
echo command instructs the Domain Test service to echo a response based on the parameters you specify. You can construct an ECHO command with one or more of the parameters below.
status=<integer>determines the status code (default 200).
payload=<urlencoded text>sets the body text or redirect url (default "").
postpayloadis an alternative to
payloadthat interprets the entire POST body as the payload.
mime=<type>determines the MIME type (default text/plain).
sleep=<seconds>causes a sleep before the response (default 0 sec, max 10 sec).
header=<name=value>adds a header to the response.
addcookie=<name=value>sets a session-scoped cookie.
delcookie=<name>deletes a cookie.
For example, the request below will return the string
The request below will return a 302 redirect to
The request below will return a 302 redirect to
http://www.example.com/ after sleeping for 10 seconds.
stash command instructs the Domain Test service to stash a response to the parameters specified in the request for later retrieval. It uses the same parameters as the
echo command. A stashed payload is truncated after 10K.
For example, the request below will stash the string 'stashed-narwhal'.
The Domain Test service responds to stash requests with a temp URL in the form below, which can be used later to retrieve the stashed response.
A single temp URL is available for use for 5 minutes after it's been generated, and it can be used once. Note that stashed data is stored in memory and should be considered highly ephemeral. Under some circumstances it may be lost even before the stated expiration time, in which case you should re-stash and try again.
Alternatively, you can use the URL below if you want to pre-generate a token before stashing:
If you’ve pre-generated a token prior to stashing a request, you can assign a stash command to your pre-generated token using the
A single pre-generated token can be used an unlimited number of times within one hour of generation.
Email Testing API
The Email Testing API allows you to trigger an automatic email response from the Domain Test service, which enables you to determine whether an application’s email stack properly handles new TLDs. You can trigger an autoresponse by sending an email with a subject that begins with the word
<local-part> is any string:
To: narwhal@domaintest.みんな Subject: Test ALL the autoresponders!
The autoresponder will reply with an email from
tester@domaintest.みんな with the subject
Automated testing service response. (Although you can send the outbound email to any address at
domaintest.みんな the autoresponse will always be sent from
tester@domaintest.みんな.) The autoresponder respects a Reply-To header, if present.
The email testing API is compliant with IDNA2008, but it does not support full email address internationalization as defined in RFCs 6530, 6531, and 6532.
If the second word of the email subject is a token retrieved from the
/token endpoint, the headers (but not body) of the incoming email will be stashed at
for 15 minutes and will be retrievable once. You can use this to determine whether an email reached the Domain Test service, even if you do not receive an autoresponse.
domaintest.みんな origin, both directly via
/echo and stored via
/stash, so it is crucial that there not be anything private within the same domain that is worth stealing. For this reason, there is no content on the domains listed below other than the Domain Test service.
You should think carefully before running the service on your own domain, since it opens an XSS vector against any other content on the domain. In addition, since stored XSS attacks can live beyond the lifetime of a stash (for example, by manipulating the HTML5 Application Cache), running the service on a domain name means that the domain name in question will always be vulnerable from a security perspective. You should not reuse a domain that is running Domain Test for any non-testing purpose, even in the future.
Testing Client Software
Suppose you’ve developed an RSS reader and want to know whether it’ll work with feeds that are served off of a new TLD. You can use the HTTP Testing API to craft a URL that returns an RSS feed. Here's an example using GET:
(In practice, it may be easier to prepare a smaller URL by using
/stash with the
You can take this URL and plug it into your app. If your app works properly --- the RSS feed loads and renders the
みんな TLD --- then you can be reasonably confident that your app properly handles this type of new TLD. If not, you’ve found a bug!
You can use the
/stash endpoint to test webhooks. Suppose you are testing a service that posts the weather to a URL of your choosing every few minutes. You can go to the
/token endpoint on domaintest.みんな and get a token that you can use with
/stash. Then you give the weather service a URL that looks like this:
This will cause the Domain Test server to save whatever gets POSTed to this URL and make it available here:
You can then poll this URL until there is something there to see. If the service successfully posted the weather to this new TLD's "webhook" then you will be able to see it. If nothing shows up, even after the weather should have been sent, you've probably found a bug!
Other Things to Try
By combining the various parameters of
/echo, you can make the Domain Test service mimic almost any kind of server. Here are some things to try:
Set a cookie using the unicode form of
.みんな and verify that it's served on the
xn--q9jyb4c ASCII version too.
Make the server present an HTTP Basic Auth challenge.
echo to serve a downloadable attachment.
If you are the registry operator of one or more TLDs, and you wish to configure an instance of domaintest for your TLD(s), follow these instructions:
- Delegate the domain domaintest.yourtld to yourself for every applicable TLD.
- Set the domains' nameservers to ns1.google.com, ns2.google.com, ns3.google.com, and ns4.google.com.
- Send an email to email@example.com with a subject line of "New Domaintest domains" and include a list of all domaintest domains that you just created.
- Wait up to a few weeks for the new sites to go live.
The discussion forum for this project is hosted on Google Groups: firstname.lastname@example.org.
Domain Test TLDs
The Domain Test tool is available on the following TLDs, thanks to a partnership between Google Registry and Ausregistry, CentralNic, Dominion, Donuts, DotClub, RightSide, The American Bible Society, Top Level Spectrum, and Uniregistry. Registries that are interested in adding TLDs to the program can email the Google Registry at email@example.com.
domaintest.boutique domaintest.build domaintest.builders