How to help testing. A step by step visual guide. (wiki) (in progress)

Welcome to your guide to becoming the best Quality Assurance engineer ever :wink: and helping to contribute to the most exciting, world changing network we will ever see. Don’t be intimidated! This stuff is easy! :sweat_smile:

. . .

ATTENTION this is a work in progress. Order of events are going to change as I learn. Please be patient and bear with me. I am hoping to have something you can work with soon. Thanks. Also if you see any errors or have suggestions please feel free to edit the wiki or just leave a comment below.
. . .




Virtual Machines



Reporting Bugs / Crashes / User Experiences



There are a few different approaches you can take to start testing. One way is to just dive in! :partying_face: There are plenty of forum members that are willing to help should you get stuck. Check out the Resources for a condensed list of links available.

If you have experience using Command Prompt or Terminal there is a great guide already set up on Github. You shouldn’t have too many problems following that, the guide goes over many items including how to highlight issues and make feature requests, the team’s development process, their commit process and so on, it even has links on how to use Github, a great resource so check it out!

This guide is mainly intended for beginner users, ones that want to help out but understandably can’t get past all that lingo. That being said, we do suggest having a look at the previously mentioned guide to see what you are getting yourself into, give you an idea of some of the teams expectations and processes, and to, a little bit, get familiar with some keywords. Our goal here is to get you involved, have some fun, and help the team out. Once you get through this guide we feel confident you will be able to move over to the official guide, start making pull requests and if you are lucky enough contribute to a commit. Even if you don’t make it that far everyone can help in some way and at times it is the most inexperienced that have a lot of value to add! Stick with us and data will be flowing from your fingers and minds in no time! :wink: .

Back to Contents

Mobile Browser Downloads

Currently you can test using Android and iOS. This is really simple and really easy.
Just download and install. Two barriers, on Android you need to authorise apps from unknown sources :innocent: and on iOS you need to register with Azure.

On Github you have multiple options available.

Back to Contents

Android Browser

You have three choices to download from, the AppCenter, Github, or if you can just scan the QR code.

  • If you choose AppCenter, easy, just press on the blue download button. Note; you may receive a notification “This type of file can harm your device…”. Just tap “OK” and the file will download.

  • If you choose Github scroll down until you see Assets (you may need to tap on the little black arrow to make the downloads appear) and press the .apk package, confirm the download and downloading should start.

  • Authorising "Unknown Sources"

    Depending on your Android version you will receive a different type of prompt when trying to install.

    • Versions below Android 8.0 apply a global setting for all app installations (you will only need to do this once for all app installs). If you have not changed this you may receive a notification “Install Blocked”, tap on “Settings” which will bring you to the “Security” page, enable the switch next to “Unknown Sources”. You will receive an extra warning, tap “OK”. Find the package you downloaded using your file manager and resume the installation.

    • Versions Android 8.0 and above apply an individual app install setting (meaning you will need to approve install for each individual app). You will be prompted to allow the permission when you try to install any app. Tap “Settings” on the prompt, then on the next screen enable the switch next to “Allow from this source”. From there tap your back button. You can then resume the installation.

Back to Contents

iOS Browser

. . .

Back to Contents

Mobile Authenticator Downloads

. . .

Back to Contents

Android Authenticator

. . .

Back to Contents

iOS Authenticator

. . .

Back to Contents

Mobile Use Cases

. . .

Back to Contents

VM's (Virtual Machines)

You may want to set yourself up a separate secure environment if you have sensitive data on your machine. Although doing this testing will not access your data for some separating the two is a necessary step. Another reason to setup VM’s is to be able to test on other operating systems (OS’s) different than the one currently installed. Playing around with other OS’s can be fun and can be an introduction to perhaps a setup you may end up preferring. Keep in mind, to use a VM you will need an ISO image, a disk image of an optical disk, of the OS you want to install.

There are a few ways to create VM’s. One preferred way is virtualbox. Some don’t like the limitations of this program such as window size and mouse issues. There are others available such as Windows Sandbox. . . Here is a great post that covers some of the stuff we are going to go over and provides a good link to obtain ISO images. Have a search online and find the VM that best suits you.

Concerning Virtualbox there are various configurations you can make, create a windows machine, a linux machine . . .

Choose your operation system and download. When downloaded, just click next, next, next and so on till you get till install. Install. (This will take several minutes). Allow the program access that it needs. Once installation has finished launch the application.

To create a linux environment on an already linux machine please see this post

For those on Windows:

Now you want to create a work environment. Click on “New” (That funny blue star to left of the green plus “add”). On the next window:

  • Choose any “Name” you wish, I chose SAFE;
  • Choose a “Machine Folder” or just leave the default as I did.
  • For “Type” choose the operating system you wish to set up (currently for this guide I am choosing Windows)
  • Choose the Version (I chose “Windows 10 (32-bit)” 64-bit is not available for me but depending on your virtualbox version it may be available for you. Choose as you wish.

Click “Next”

You will now see a choice for memory usage; Just leave it at default and click “Next”.


You will now see a choice on creation of Hard Disk. Virtualbox’s recommended size is 50GB. But for testing 4GB should be enough. If you are unsure about how much disk space you have free do the following:

  • Right click on the windows icon, depending on your setup this is by default on the bottom left of your screen, if you customised it like I did, it is on the top left…

  • I am not able to get a screenshot but after right-clicking a bunch of options will show up in a drop down menu. Select “Disk Management”

  • Windows 10 will ask you (at least it does me) if I want to authorise the app to make changes, just click “yes”.

  • You will now see a screen which shows you how much space is available on your hard disk.

  • If you are happy with giving up 4GB to create your virtual disk go back to the “Oracle VM VirtualBox Manager” which should still be open as a “tab” in your “taskbar” (the bar with all the icons generally at the bottom of your screen). And click “Create”.

  • You will now see a window asking for the Hard Disk File Type, reading the directions, just click “Next”. You are creating a “VDI”, a “VirtualBox Disk Image”.


  • You will now see a choice on how much space this virtual machine will eventually take up on your hard drive. Even though we just allocated 4GB for the initial install you can now choose if you want to allow additional space on top of the 4GB if the Virtual Machine eventually needs it. I am choosing “fixed size” as I think for this exercise it should be enough and it is faster to use. If you want to be 100% sure you will have enough space choose Dynamic Make your selection and click “Next”.


The next screen you see may seem repetitive, it is just confirming everything you previously setup is correct to your liking and allowing you the option to change if you wish. Just click “Create”.

Your application will now create a Virtual Hard Disk, depending on your computer resources this may take some time. Mine says it will take “7 minutes”. This may take longer or less, from my experience computers aren’t very good at estimating time. You may also notice a lag in other affairs in your computer as it is working hard! Just let it do its work and be patient.


Back to Contents

Desktop Browser Downloads

. . .

Back to Contents

Windows Browser

. . .

Back to Contents

OSX Browser

. . .

Back to Contents

Linux Browser

. . .

Back to Contents

Desktop Authenticator Downloads

. . .

Back to Contents

Windows Authenticator

. . .

Back to Contents

OSX Authenticator

. . .

Back to Contents

Linux Authenticator

. . .

Back to Contents

**Desktop Use Cases**

. . .

Back to Contents


CLI is an acronym for Command Line Interface commonly known as the Command Prompt on Windows and Terminal on OSX. These Terminal Emulator’s are GUI’s (Graphical User Interface’s) that allow a user to interact with The shell. The Shell is a command-line interface program that takes commands from the user as an input, processes the command, and prints out the output to the display.

Linux users regularly use Terminal Emulators to install/uninstall programs and run various commands although over the years Linux’s various operating system’s GUI’s have gotten much better removing this necessity.

Using the CLI can seem very intimidating and very geeky especially to new users. But, it actually is quite simple and can be fun to work with.

Maidsafe already has a great guide on how to install their CLI on github that I cannot improve on much. For Windows users I can run you through the install process visually. And then later in this guide we can run through some tests together.

Back to Contents

CLI Testing

. . .

Back to Contents

Reporting Bugs / Crashes / User Experiences

. . .

Back to Contents


. . .

Back to Contents


Yes, it’s great, but too geeky, no offense @ devs, I would like to encourage “regular joe” testing as feedback can be very helpful. Visual baby step by step guides making it less intimidating. I would like to encourage more “lurker” “non-technical” engagement. Also, putting it here directly on the forum I think is also less intimidating vs. github…


Yes and feedback on user experience is important as much as what is obviously a bug.

There are so many use cases for SAFE that there’s a lot of opportunity for everyone to contribute.


Keep going. Please please


I will try my best. Just so you know. I work on quite a few other projects. My goal is to work on this at night when I should be sleeping :grimacing: . As I said

So, a bit of research on this forum is going to need to be done, the information is there I am pretty sure, just have to dig to find it :+1:

Edited to add, the admin has kindly made this a wiki so if anyone has time, or feels the desire, to share the knowledge/links, please do so :slight_smile:


I actually understood your original post. Great for non techies like me. No stress but I will keep my eyes peeled


ach, there is an error there no, not sure why i created a virtual disk image, it should be a virtual hard drive, :sweat_smile:

1 Like

Questions I have, for others if they wish and also a note to myself to research further.

Can a user create a virtual hard disk smaller than 50GB? Meaning specific to this testing what is the recommended disk size needed?

When the user has finished with their testing or if they make a mistake or if they give up is getting rid of the partition easy?

Some links I have found so far that may be helpful in creating this guide:

I can. I can also select 64 Bit Windows so we must have different setups.

As a side note, I think you should mention earlier you’ll you need a Windows ISO image on your machine for the next stage.

To be honest, I wouldn’t bother with VirtualBox unless you have a Windows machine and want to run Linux. It’s a lot of extra fiddling about and there’s not too much that can go wrong with the SAFE stuff if you follow the instructions - in that it might not work but it won’t trash your machine.


Cool. Thanks for the feedback. I will update the wiki tonight to make the virtualbox for testing with Linux.


I hope this screenshot - and the others to follow shorty will help.

I am actually creating a Linux machine within a Linux machine but the UX is pretty similar on both Linux and WIndows

The absolute first requirement is a Linux install .iso. There are many choices but for here I think a plain vanilla Ubuntu 18.04 desktop may suit most folk

OR Your could grab an image from
There are a variety of pre-built images there that can get you started immediately.

So download that now while you get on with everything else.

Ubuntu will run in as little as 1024MB. As you can see I have given it 4GB above because I have plenty RAM to spare. You decide but anything over 4GB is overkill.

Create the virtual hard disk

10GB is plenty unless you really want to stress a section on your own computer. For connecting to the Maidsafe hosted shared-section 10GB is more than enough. Just accept the default .vdi option, no need to complicate things.
Dynamically allocated means that VirtualBox (VB) will only allocate the disk space that is actually used - so you are not immediately writing off a whole 10GB. Its a little bit slower this way but IMHO fine for our purposes now

So the next screen you will see should look like this - minus the list of other VMs on the left

Now highlight your SAFE test environment on the lft, go to Setting (top centre) and click Storage, then the wee CD iicon on the right

If you saved your downloaded Ubuntu .iso to /Downloads then it should appear here
Click to select.


Now go to Settings | Network and select BridgedAdapter - note the actual name of your adapter may well be different

Audio (optional)

If you want to listen to sounds on SAFE safe://safe-blues <–TODO check this
then you need to enable audio in your VM

Shared Folders (optional)
You might want to enable this if say you have websites already built on your machine that would like to try PUTing onto the shared-section.
Skip for now if you don’t.


I have usually just accepted the defaults here and it Just Works for anything as straightforward (in VM terms) as testing SAFE

That should be our VM setup complete - Hit start and you will come to this screen

Choose your language and (in English) this is your next choice

Take the second option Install Ubuntu - its a VM if anything goes wrong, we simply delete and try again. That’s the beauty of VMs :slight_smile: After a short wait, we get this

Choose your language, keyboard layout. Then we come to some more installation options. It’s up to you but these are my choices.

Then choose where to install Ubuntu. We are working with a virtual disk, it CANNOT affect your existing operating system(s) or data. So this choice is perfectly safe
Trust me, I’m a random bullshitter on teh intrawebs… No seriously it IS OK.

Click “Install now” and confirm to format the partition ON YOUR VIRTUAL DISK - Do not worry. I know I certainly did the first time I tried this…

Then tell the install who you are. For this case, and this case ONLY, its perfectly OK to click “log on automatically”. You are not going to put anything valuable on this install.
Remember your password though -even if it is weak.

Hit “Continue” and find something interesting to do for 5 mins or so.

You should eventually see this

Restart your virtual machine and you will get this message

Hit next a few times to go through some options - just accept defaults - and then you get this screen

Hit “Install now” and try to remember the password you set 10-15 mins ago.

Once this is complete, you should have an up to date version of Ubuntu 18.04 installed on your virtual hard drive, ready to download the latest safe-browser and safe-cli.


For testing on Windows, Windows Sandbox could be useful.


Killer! This is great! Thanks everyone! Long day today…on a Sunday at that, must eat, must sleep. I will be working hard on this tomorrow night…you all have my word.


Awesome thread guys, thanks for kicking this off @Haigha :muscle:

As a macOS user, I use virtualbox for Windows & Linux testing when required - the process seems pretty much identical to the steps listed by both Haigha and Southside above. If you need me to check any specifics from a macOS perspective just let me know.

One thing I have come across in the past is issues with VM hard disk space if you intend to manually build projects. Projects such as safe_vault and safe-api use up a fair amount of hard disk space once built locally. This probably isn’t applicable to the majority of users who would more likely download the binaries and use them, rather than build full projects, however like JPL said above there probably isn’t much need for a VM (IMO) if you are just intending to try out a downloaded binary (unless you wanted to try on a different OS).

For anyone wondering why someone would want to build projects themselves rather than just download the latest binary - we release new binaries for our different projects periodically when we believe that a relevant amount of progress has been made to justify a new version, and enough testing has been done in the meantime to feel confident that the new version is stable enough for public release. However, as our projects are fully public on GitHub, anyone is able to view and clone/fork, then build the latest code before we have officially packaged and released it ourselves. Some people want to try out new features or fixes this way before they are officially released, for example it may be a feature or fix that is blocking them from making progress on a project of their own. Some may also wish to tweak the code to build modified binaries of their own.

Back to VMs. For Linux/Unix VMs I can recommend the open source images you can download from These ready-to-use images have some additional software pre-installed for you on them to save you installing yourself, software such as Firefox and VirtualBox Guest Additions. Just saves a little extra work installing these once start your new VM.


That’s a great tip. VirtualBox is good but one of my concerns recommending it is all the faffing around required to get the screen size to expand to more than 800px and getting the mouse working properly - the Guest Additions stuff in other words. I find it unintuitive and have to look it up every time. If it’s preinstalled on those images that would certainly ease the learning curve.


Good point. Most of my VM work is CLI so its less of an issue for me. Certainly for linux guests, the mouse has Just Worked for a couple of years now.
Screen size can be a bit of a PITA but scaled mode is OK(ish). I’m not looking for hi-res graphics here.

Also a good point - I will update my walk-through to add this later


Are these VM the same kind of machines that cloud based services offer?.. I’ve yet to use those with a desktop… though have had success recently with local TigerVnc and guess necessarily all these work in a similar way.

1 Like

Well a virtual machine is a virtual machine. Its the exact spec that matters.
The difference is doing it as described above is it is YOUR VM that is subject to YOUR rules, not theirs. And its much cheaper because (generally) you are making use of unused resources you have already paid for - which is SAFE-like in itself.

I feel so slow when I am tired.

Getting through it but slowly, just gotta get the layout right and organised, afterwards finding the details and making screenshots.

I have decided to run through the mobile browser and authenticator first;

  1. to encourage downloading and

  2. It is really easy to do so can be motivating to move forward with more complicated things.

  3. I do not have an iphone, so if anyone does and could post screenshots on the install process of the latest browser and auth that would be great.

I am having a hard time finding links, I made a post on meta about it and thoughts there might be helpful. Unless I am corrected and completely missing something.

Great feedback/info from everyone, thanks all! :+1: @southside’s post put me to shame too :+1:

I am very eager to start figuring out the CLI so want to knock out the easier stuff as fast as possible, daily time is limited though but I hope to not take too long. Cheers.