Write `Starting with GitLab QA` documentation
Documentation
It is quite difficult to start writing high-quality GitLab QA specs now. After a few weeks of reviewing merge requests, I think we should make it easier for developers to start working with GitLab QA.
Proposal
Add CONTRIBUTING.md
documentation that will cover most important end-to-end testing principles for someone who is just starting writing QA specs.
We already do have some docs, but we need one single document that will document most important things.
Some ideas about what it should cover:
- Explain what GitLab QA is, link to existing documentation, architecture diagram etc.
- Explain why we are using Page Objects, and why this concept is important, link to existing docs in
qa/qa/page/README.md
. - Link to existing docs about development on MacOS.
- Why we should have black-box / user-oriented approach (why having 100 lines of JavaScript with
page.evaluate_script
in specs is usually not a good idea) - When it is helpful and needed to extend the GitLab QA framework itself, encourage developers to dive into the framework too. Provide examples.
- Write a few stories about writing complex test scenarios (for example for Geo) and how we approached it.
- Write docs about using Factories
➡ #156 (closed) - Document we should not assert on selectors in
_spec.rb
files, assert only on page objects instead - Document using
qa/
qa-
prefixes / suffixes to limit amount of jobs being run in a pipeline. - Why we should focus on using tools that users are going to use instead of bundling Ruby gems that are supposed to replace tools (
git
,ssh
). - Explain why we are using Docker extensively and why it is sometimes difficult to contribute when your are not using Linux.
/cc @rymai @bjgopinath
Edited by Bj Gopinath