573874 - Add content to readme files in mozmill-tests

Status: RESOLVED FIXED

(Mozilla QA Graveyard :: Mozmill Tests, defect)

Description

[Jeff Hammel]

http://hg.mozilla.org/qa/mozmill-tests/raw-file/tip/readme.txt is an empty ; it shouldn't be.  It should be wiped or content added.

Comment 1

[[:Aleksej]]

There are more such files, either empty or with "This is a place holder file".

$ find -name readme.txt
./templates/readme.txt
./readme.txt
./firefox/readme.txt
./addons/readme.txt
./shared-modules/readme.txt

Comment 2

[Henrik Skupin [:whimboo][⌚️UTC+1]]

Why has this been filed in the Mozmill product? Moving to tests.

Comment 3

[Dave Hunt [:davehunt] [he/him] ⌚BST]

I would suggest the following content for these files:

Licence information

General project information - A brief description of the Mozmill Tests project, which will appear at the top of each readme.txt file. Also will include a link to QMO's Getting Started page for further information (http://quality.mozilla.org/docs/mozmill/getting-started/).

Specific location information - A description of the location the readme.txt file is located in, plus a link to any relevant documentation on MDN.

If this sounds good then I can work on a patch to add this to the files.

Comment 4

[Aaron Train [:aaronmt]]

(In reply to comment #3)
> Specific location information - A description of the location the readme.txt
> file is located in, plus a link to any relevant documentation on MDN.

That's good, I particular would like to see the getting started, and getting the environment setup information.

Comment 5

[Henrik Skupin [:whimboo][⌚️UTC+1]]

(In reply to comment #3)
> Licence information

I don't think that there is any need to put any license information into the readme files. Do we have anything to protect? 

> General project information - A brief description of the Mozmill Tests project,
> which will appear at the top of each readme.txt file. Also will include a link
> to QMO's Getting Started page for further information
> (http://quality.mozilla.org/docs/mozmill/getting-started/).

IMO it should be enough to place that overview description in the top level readme file. The other ones specific to available test-runs should only contain specific information about the covered area. What do others think?

> Specific location information - A description of the location the readme.txt
> file is located in, plus a link to any relevant documentation on MDN.

I would also point out, how to run the tests under this folder, i.e. linking to the automation scripts.

Comment 6

[Dave Hunt [:davehunt] [he/him] ⌚BST]

Attachment: Suggested content for readme files.

Attached suggested content for readme files. I like the idea of including some detail on the automation scripts, but am not familiar enough with these yet to know what to write. Please make suggestions.

Comment 7

[Henrik Skupin [:whimboo][⌚️UTC+1]]

Comment on attachment 494396 [details] [diff] [review]
Suggested content for readme files.

>+++ b/addons/readme.txt
>@@ -0,0 +1,8 @@
>+#ÊAddons #

There is non-unicode character, which shouldn't be here.

Also we should mention it as "Add-on Tests", same as on the project page:
https://wiki.mozilla.org/QA/Mozmill_Test_Automation/Addon_Tests

>+In addition to using Mozmill to test the application itself, it is also possible
>+to test any kind of add-on. Creating a test for an add-on is not much different
>+from creating Mozmill tests for Firefox itself.
>+
>+For more information on Addons Tests visit:
>+https://developer.mozilla.org/en/Mozmill_Tests/Addon_tests

I would reference the project page, which should normally get all the information we have on MDN right now. Until it has been re-worked the project page can link to the MDN page.

>\ No newline at end of file

Please place an empty line at the end of all files.

>+++ b/firefox/readme.txt
>+# Firefox Normal Tests #

We always had problems correctly naming those tests. Lately while talking about Tinderbox, we came across non-restart tests. I think we should stick with this term, which makes it clearer.

>+This location holds the Mozmill tests for Firefox. When running Mozmill with a
>+target of this directory, all subdirectories with the prefix test will be
>+processed, and any files within those directories also with a prefix of 'test'
>+will be run.

The second sentence you have here, does fundamentally apply to all Mozmill tests. It's described on MDN in detail. So lets keep this section for details about this specific test-run. 

>+Also contained in this location is the restartTests, which must be run using the
>+command line version of Mozmill, using the mozmill-restart command. This allows

Did you miss the 'folder' after restartTests?

>+++ b/readme.txt
>+Mozmill Tests contains JavaScript tests for the Mozilla Firefox product, which

Mozmill tests are written in Javascript.

>+can be run using either the Mozmill IDE Firefox Addon, or the Mozmill Command

Could you just say: "the Mozmill add-on for Firefox, or the Mozmill command line client"?

>+If you have questions, feel free to join us in #mozmill on irc.mozill.org or use

you missed an 'a': irc.mozilla.org

>+++ b/shared-modules/readme.txt
>+# Standard Modules #

Can you stick with shared?

>+to be accessed probably over and over again, mostly in the same order. To make
>+it easier to work with those elements and to reply a path of events, shared
>+modules have been implemented which contain helper classes and helper functions
>+with a focus to such an user interface. Some of them are special for Firefox

I'm not native English speaker, but this sentence is quite long and hard to understand for me. Not sure, if it's because of some missing commas.

>+++ b/templates/readme.txt
>+To make it easier for you to create your first Mozmill tests, we have prepared a
>+couple of template files. They will help you get familiar with the license
>+block, needed test functions, shared modules, and the proper syntax to use when
>+writing tests.

Instead of syntax I would call out the coding style.

>+For more assistance writing new tests visit:
>+https://developer.mozilla.org/en/Mozmill_Tests#Writing_Mozmill_tests

Hm, linking https://wiki.mozilla.org/QA/Mozmill_Test_Automation/Test_Writing?

Comment 8

[Geo Mealer [:geo] -- This account is inactive after 2015-07-07]

> >+to be accessed probably over and over again, mostly in the same order. To make
> >+it easier to work with those elements and to reply a path of events, shared
> >+modules have been implemented which contain helper classes and helper functions
> >+with a focus to such an user interface. Some of them are special for Firefox
> 
> I'm not native English speaker, but this sentence is quite long and hard to
> understand for me. Not sure, if it's because of some missing commas.

I'd break it up. Also, not sure "reply" makes sense to me when used that way. Programming term I'd use is "encapsulate" but it's techie. How's this?

To make it easier to work with those elements and execute common actions, shared modules have been implemented. These modules contain helper classes and helper functions, with a focus on user interface.

Comment 9

[Dave Hunt [:davehunt] [he/him] ⌚BST]

Attachment: Suggested content for readme files v2

I agree with all points raised. I've addressed them all in the revised patch.

Henrik: The paragraph on Shared Modules was actually taken from MDN, I believe contributed by yourself. If you are happy with the version in this patch I would also suggest updating MDN. Let me know if you'd like me to do this.

Comment 10

[Henrik Skupin [:whimboo][⌚️UTC+1]]

Comment on attachment 495025 [details] [diff] [review]
Suggested content for readme files v2

There is only one single nit I have until we can check-in those docs:

>+++ b/readme.txt
>+# Mozmill Tests #
>+
>+Mozmill tests are written in JavaScript tests for the Mozilla Firefox product,

Whether the "in" is too much here, or you will have to update the sentence a bit.

r=me with this update. Can you also please qrefresh your patch with the "-m" option to add a commit message? See our pushlog how it should look like: http://hg.mozilla.org/qa/mozmill-tests/pushloghtml

Comment 11

[Dave Hunt [:davehunt] [he/him] ⌚BST]

Attachment: Suggested content for readme files v3

Addressed nit, and added commit message.

Comment 12

[Dave Hunt [:davehunt] [he/him] ⌚BST]

What do I need to do with this? I'd kinda assumed it'd be landed by someone. Do I need to do anything?

Comment 13

[Henrik Skupin [:whimboo][⌚️UTC+1]]

Sorry, missed it during the week.

Has been landed as:
http://hg.mozilla.org/qa/mozmill-tests/rev/989ed0de3535 (default)
http://hg.mozilla.org/qa/mozmill-tests/rev/3c32aa23b542 (1.9.2)
http://hg.mozilla.org/qa/mozmill-tests/rev/96b28251ab8f (1.9.1)