I am in the process of designing and building a small web app. While implementing a first prototype I discovered that I make many unwritten assumptions about the behaviour of the interface. For example:

When the user selects a product in the product browser, the product inspector quickly slides out the left side displaying the product data. If the inspector is already opened, the data is only updated. The header background color changes with a radial animation.

Right now it's just me on the project, so I define these implicit requirements on the fly. But after every change that could break something I have to recall all of them in order to test them. I obviously should write them down somewhere. I know unit testing, I know scenarios and personas, use-case diagrams; this seems to be something different and I don't know how to do it properly.

So, what is the usual way of defining, documenting, and also guaranteeing such requirements? Where do I put them? How do I structure them? How do I test them effectively? Should I ship them with the source code or put them in the project Wiki?

Also, these requirements are likely to change frequently, especially since I am using a rapid prototyping approach. I do not want to spend a lot of time drawing diagrams, etc. But simply dumping them into a text file without any structure seems to be a time waster as well, as soon as I have to test a specific part of the application.

2 Answers 2


Sure, rapid prototyping can lead to frequent changes on your APIs for a duration of time, but I will expect changes to eventually mature and stabilize after requirements fall into place and you can essentially do an 'API freeze'.

If you are making changes to undo past changes, then you may be getting ahead of yourself and straying away from the You Aren't Gonna Need It principle. The point here is to know when and how you need to put a stop to making more requirements' changes.

With that out of the way, I think unit testing is definitely a potential starting point to validate any new changes you think you are going to implement with what is working currently. However, don't code weak unit tests that are either incomplete, or only performing the more superficial test cases (e.g. making sure fail-fast for null arguments work, without stepping through the actual logic). Try to unit-test for more meaningful edge cases, which tend to be your first line of defense when you head back to the drawing board. It will be even more helpful if you can write your unit tests in a BDD-style that gives a good definition of a class's contract.

You should also try to document your API design/code from the viewpoint of an end-user, or as a tabula rasa developer. Linking to the first point, once you feel you have reached a sufficiently mature point of your API design, start to document your codebase from scratch. Make sure to update the parts where your original 'implicit requirements' have changed. These can be included on your project's wiki page. If you are also placing your project documentation under version control, e.g. putting them up on GitHub, then you will also have a working version history to learn how the documentation plus your codebase have evolved.

  • 1
    Thank you for your answer! For APIs I already know how to document (interfaces, comments) and test properly (unit tests). I have trouble documenting and testing requirements that are less tangible and not easy to test automatically. But I guess I'll really just add them to the Wiki. After all they are just requirements like any other and I can document them like everything else.
    – Lucius
    Aug 25, 2015 at 10:51

Selenium IDE allows you to walk through a scenario and add assertions to check it works as expected. which you can then save as a file you can play back later. It does have a few limitations.

  • the extension only works in firefox.
  • checking for visual changes may be difficult. ( it looks like you can check css properties )

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.