Contributing to Test Lists

Censorship findings are only as interesting as the sites and services that you test.

We encourage you to suggest sites and services to test for censorship.

Please read the documentation below to contribute to community resources for censorship measurement research.

What are test lists?

Test lists are lists that include URLs that are tested for censorship.

The Citizen Lab supports OONI and other censorship measurement projects with a public resource that includes the following:

The global list includes a wide range of internationally relevant websites, most of which are in English.

Each country-specific test list includes websites that are relevant and commonly accessed within that country, many of which are in local languages.

The URLs included in these lists fall under 30 categories, ranging from news media, file sharing and culture, to provocative or objectionable categories, like pornography, political criticism and hate speech.

Why contribute to test lists?

1. You can provide local expertise

Examining internet censorship in a country requires local expertise, an understanding of:

To ensure that test lists include a variety of different types of URLs that are updated on an ongoing basis, we need community contributions from around the world.

2. Potential risks

When running ooniprobe, you will connect to and download data from the websites included in the global test list and in the test list which is specific to the country that you are running ooniprobe from.

We therefore encourage you to review all of the URLs included in these lists carefully, prior to running ooniprobe, as connecting to some of these websites might be legally questionable (or illegal) in some jurisdictions.

If you are uncertain of the potential implications of connecting to and downloading data from the websites listed in the test lists, you can pass your own test list with the following type of command line option:

ooniprobe <test-name> -f <your-test-list>

Contributing to test lists

You can contribute to test lists in 2 ways:

Reviewing test lists

All test lists that ooniprobe is designed to test for censorship are hosted in the Citizen Lab’s test-list repository on github.

To review country-specific test lists, please follow the steps below:

Step 1. Find the csv file which is specific to the country that you want to run ooniprobe from (based on that country’s code) here.

If you don’t find a csv file for your country, that’s probably because it doesn’t exist yet. In this case, please refer to the next section on “Creating new test lists”.

Step 2. Add new URLs to the csv file under the “url” column.

Some criteria for adding new URLs can include the following:

For further criteria, please view the URL categories here.

Please try to add URLs which fall under as many (if not all) of these categories as possible.

Step 3. Every time you add a URL, please add the following in the csv file for each new URL:

Step 4. Change the category codes and descriptions for URLs (included under the “category_code” and “category_description” columns of the csv file) only if you think that those URLs have been allocated to wrong category codes and descriptions. In this case, please replace the category codes and descriptions with ones (from the recommended categories that you think are more suitable. We would also appreciate a comment on github or via email explaining the proposed changes.

Step 5. Once you have reviewed a test list based on the above, please submit your changes to us. If you’re a github user, you can do so through a pull request. If you’re not a github user, please send us a spreadsheet (including the same format as github csv files) by dropping us an email at contact@openobservatory.org (PGP Key Fingerprint: 4C15 DDA9 96C6 C0CF 48BD 3309 6B29 43F0 0CB1 77B7).

Creating new test lists

If you can’t find a test list specific to your country here, then it probably does not exist yet. Please help us create a test list for your country through the steps below:

Step 1. Create a csv file and name it based on an ISO-3166 two-letter country code which is specific to the country that URLs are being added for. You can find a reference for international standards for country codes here. An example would include a csv file created for Andora, named ad.csv.

Step 2. Include the following columns in the newly created csv file:

Step 3. Add URLs under the “url” column of the csv file.

Some criteria for adding new URLs can include the following:

For further criteria, please view URL categories here.

Step 4. Every time you add a URL, please add the following in the csv file for each new URL:

Step 5. Once you have created a new test list based on the above, please submit your csv file to us. If you’re a github user, you can do so through a pull request. If you’re not a github user, please send us your csv file by dropping us an email at contact@openobservatory.org (PGP Key Fingerprint: 4C15 DDA9 96C6 C0CF 48BD 3309 6B29 43F0 0CB1 77B7).

## Important tips

  1. Always include the full URL, including the HTTP or HTTPS prefix, exactly as it appears when you type it into a browser. If you include example.com in a test list, ooniprobe won’t be able to test it. Rather, it should be included as http://www.example.com, if that is what it looks like in a browser.

  2. Always use the format described in the sections above. The test lists are meant to be machine-readable, and ooniprobe will not parse test lists that don’t strictly follow the prescribed format.

  3. Please stick to the categories included here, and refrain from adding your own categories. The categories may not be perfect, and we welcome your suggestions for additional/alternative categories. But if you don’t use the prescribed category codes, ooniprobe will not be able to test those URLs, since test lists are meant to be machine-readable.

  4. Please do not scrape and add “the top 1,000 Alexa sites”. Community contributions are more useful when they include URLs that (a) fall under these 30 diverse categories and (b) reflect local insight. Given that many ooniprobe users around the world have bandwidth constraints, we favour quality over quantity in terms of what is tested.

Thanks for contributing!