A Guide to Being an Effective Beta Tester
Welcome
Why beta testing is important
Our QA staff works hard to make sure that our releases are stable, but there is no way we could do it without members of our developer community providing feedback on upcoming builds. We’re very happy that you want to help out!
To help you help us (help you), we have created this guide to being the best beta tester you can be - how to upload your project, how to write a bug report, and more. Following these steps will allow you to provide us with the most important information so we can fix problems that affect you and the development of your projects.
Your feedback on the beta is invaluable. We analyze every beta bug report rated 4 and 5, and do our best to look at those with lower ratings (if you’re not sure what that means, take a look at this blog post). When we have validated the bug and have a fix, we will schedule it for an upcoming beta release. We are currently unable to provide details on which fix will be in which beta, but know that it will be as soon as possible!
Below you will find detailed information about the workflow for submitting impactful bug reports and feedback. Here you can also find a summary of the most important steps.
If you have further questions about the beta, visit the beta forum.
Contents
Download the latest beta build, either directly as a standalone installer or via the new Unity Hub. This page also contains lots of beta information and resources. You can learn about new features, find helpful documents and tools, and stay informed about the latest sweepstakes.
Run the Installer or the Hub. If you use the installer, be sure to install the beta in a new directory. It’s ok to have multiple versions of Unity side by side, as long as they are located in individual directories.
Start a new project or make a copy of the project you plan to use for testing the beta, then open it with the latest beta version.
Develop as usual and/or test new features and updates. If you think you found a bug, follow the next steps described in parts two, three, & four of this guide.
So… you found a bug. This is how you can help most efficiently.
Assess the situation Primary actions Secondary actions Check the issue tracker for existing bug reports.
Google the issue and look for related forum threads.
Is it a known unresolved issue?
Vote for the relevant issue tracker entry.
Is it an unknown issue?
Submit a bug report with a minimal reproduction project and respond to requests from Unity personnel.
Was the issue already reported, but you want to make sure your case will be covered by a fix?
Submit a bug report with a minimal reproduction project and respond to requests from Unity personnel.
Is there an existing forum thread about the issue?
Reply. If not, start one referencing your Issue ID.
If you run into an issue with Unity, the first thing you should do is to find out whether it is a known issue or if you’re the first to experience it. The first address to get this kind of information is our public Issue Tracker. It allows you to search for bugs reported by other users and vote or comment on them. Voting on issues helps our team prioritize which bugs to tackle first.
The Unity beta forum is another great community resource. You can see what other people have reported, find workarounds for issues, or provide information yourself. It’s also a good way to get in touch with someone at Unity. Just make sure that the subjects you’re raising are related to the current beta, and don’t bundle multiple different issues in a single thread.
If you don’t find anything related to your bug, then it’s time to submit a bug report. Once you’ve submitted a report, it’s also a good idea to come back to the forum and post a description of the issue you’ve discovered. Doing so will enable others to inform themselves and add more context or provide their workaround. It will also speed up processing times, since we’re monitoring the beta forum frequently and prioritize the initial assessment of new cases that are discussed there.
If you start a new thread about an issue, please make sure to include your Case number (provided in your confirmation email) in the post so that our team can identify the bug report you submitted - it’s the first thing they will ask if you leave it out.
If you’re in doubt whether an issue points towards a bug in the platform or your project and consulting the forums or documentation doesn’t bring certainty, please go and submit a bug report anyway.
Bug reporting can seem a bit intimidating at first but it’s really not so tough, and it is vital to ensuring stability. Follow these simple steps to write a good bug report that our engineers will be able to easily understand and act on.
Don’t be afraid of making mistakes. If we can’t reproduce an issue with the information provided in your report, we will get in touch with you to figure out if something is missing.
Open the Bug Reporter
While running Unity, go to Help → Report a Bug in the menu. Alternatively you can find the Bug Reporter installed next to the editor in the program folder. It will also launch automatically if you experience a crash.
Provide Basic Information
In the “What is the problem related to” field, select whichever option aligns best with the bug you are reporting. Since you’re reporting a bug in the beta, it will usually be “A problem with the Editor” or “Crash Bug.”
In “How often does it happen,” you will need to indicate if this is a problem that you have only experienced once, sometimes, or every time you take the steps that led you to encounter it.
Provide your email address in case our team needs to contact you for more information. If you’re logged in with your Unity account, this field will be filled automatically.
If your report gets verified, the text written in the “Title” and “Describe the problem” fields will be made publicly available in the Issue Tracker. This helps the community. Other users will be able to comment, vote (which aids with prioritization for fixes), and see when a fix is available. None of your personal information will be published. Your projects and other attachments are only accessible to Unity employees.
Identify the bug
In the most concise terms, how would you describe the bug? Keep it short and specific, like:
Errors appear in the console after cleaning GI Cache and reloading project
Categorize the bug and write the title
If you had to categorize the bug, what would you pick? UI? Asset import? Scripting? Specific platform? Crash? In this case, the bug was related to lighting and more specifically to the Enlighten lightmapper.
Okay, now add that and your bug description to create the title in the following format:
[Category] description
In this scenario, your bug title would look like this:
[Enlighten] Errors appear in the console after cleaning GI Cache and reloading project
Provide the steps to reproduce
The Unity QA and Development teams need all the help you can offer in diagnosing and fixing an issue. Depending on the information they receive, they may not be able to identify the root issue, or they may get misled and fix something else that isn’t your bug. So, it’s in your interest to provide as much information as possible up front to make sure your issue definitively gets addressed.The easiest way to do this is usually to backtrack through the steps you took prior to encountering the bug. So, what was the very first thing you did before you saw the bug?
Close and reopen the project
So that is the last step in the Steps to Reproduce. What did you do right before that?
Clean the GI cache: Edit > Preferences > GI Cache > Clean Cache
Keep doing this as far back as you can remember, ideally to when you first opened up Unity. The more information you can provide, the easier it will be to reproduce and fix. If you can’t remember everything, see if you can reproduce the bug and pay attention to the steps that you’re taking.
Please note that you do not need to provide the steps in written form - for instance, you can submit the steps via video capture of your screen. What is most important is that it clearly illustrates the steps so that our engineers can recreate the bug.
Add expected vs actual results
What did you think would happen before you encountered the bug?
Expected: no errors in the console
What happened instead?
Actual: errors appear in the console
Note, that if you encounter unexpected error messages it is helpful to add those to the description as well.
After filling in all that information, your report should now look like this:
Attach your project folder
The Bug Reporter will automatically include the currently loaded project in the bug report if you open it through the editor. If you start the reporter via its executable file, you will have to attach your project manually. Unless your project is already very small, it is recommended to strip it of irrelevant assets. Submitting a minimal reproduction project that only contains what is necessary allows our QA and Development teams to isolate the issue more efficiently and provide a fix much faster.
If the issue occurs in a specific scene of your project, try exporting the scene in which you encounter the bug, then import it into a new project and see if the bug still occurs. If it does, upload the new, smaller project. If it doesn’t, you can keep trying with larger versions of the project.
To help you reduce the size of your projects and to create minimal reproduction projects, we developed several tools that greatly reduce the required effort.
You can find additional information on how to use these tools here.
The smallest project that recreates the issue is ideal, but large projects are definitely better than nothing, so please do include your whole project if you’re unable to narrow it down. Our reporting system supports huge attachments. Please do not upload individual assets because the project contains relevant data and files that the assets alone do not.
The final report should now look like this:
Perfect! You’ve put together an informative and concise bug report that our team can use to find and fix the issue. Just one last step:
Submit your bug report
Hit “Send” to submit your bug report.
When your bug is submitted, you will be sent a confirmation email containing the case number, which you’ll need to hold on to. The email will include a link to a web page with the current status of the bug. You can check back on that page anytime for an update. Don’t share this link on the forum or other public spaces, as it reveals your contact address and bug report history. The case number is sufficient for others to find the issue on the Issue Tracker.
For your personal convenience, we suggest that you keep track of your bug reports and related project folders. We recommend the following approach:
Anytime you submit a bug report, create a .zip file of the project that you attached.
Keep a .txt file of the bug report itself and keep it in the Assets directory so that you know what error the project shows and how you can reproduce it.
After you submit the bug report, grab the case number provided in the confirmation email and prefix your .zip file with it.
This way, you can quickly find the project you attached to a report once Unity sends you an email to notify you that your bug report has been closed.
Upon receiving the notification from Unity regarding your bug report being closed, you can check to see if the bug has been fixed by finding the appropriate project and opening in the latest Unity beta. Follow the steps to reproduce, and you can easily determine if the bug is gone.
While this is a bit of work on your end, it means a) you are more likely to have a high-quality bug report, which means your bug is more likely to be reproduced and fixed, and b) you can easily ensure that the bug has been fixed in a future beta version.
It is always ideal for our staff to be able to get in touch with you in case they have questions. If you submitted a bug report, we will reach out to you via email. If you wrote in the forum, we will reply there. Please respond as soon as possible to questions and requests you receive from the team to ensure a speedy resolution of the case.
If you didn’t see your bug mentioned in the forums, we advise you to start a new thread. Remember that others may have experienced the same problem, so posting any workarounds you find is a fast way to make friends in the beta community!
That’s it!
Thank you for taking the time to learn how to be an effective beta tester. If you have questions about any of the above and your search engine of choice doesn’t reveal any answers, please drop by at the forums and ask.