cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dblotsky <...@git.apache.org>
Subject [GitHub] cordova-medic pull request: Medic Refactor
Date Tue, 10 Mar 2015 01:54:01 GMT
Github user dblotsky commented on a diff in the pull request:

    https://github.com/apache/cordova-medic/pull/37#discussion_r26093874
  
    --- Diff: README.md ---
    @@ -1,166 +1,173 @@
    -Medic using BuildBot
    -=======
    -
    -> Tools for Automated Testing of Cordova
    -
    -# Supported Cordova Platforms
    -- On Mac
    -  - iOS
    -  - Android
    -- On Windows
    -  - Android
    -  - Windows Phone 8
    -  - Windows Universal Apps (Windows 8.0, Windows 8.1, Windows Phone 8.1)
    -
    -#Installation
    -##Select target OS
    -Install on a Mac or Windows depending on target test platform(s)
    -
    -##Install prerequisites
    -medic requires grunt-cli npm package to be installed globally. You can install it by
typing `npm install -g grunt-cli` in console.
    -
    -**Note:** this requires admin privileges on Mac OS.
    -
    -## Setup CouchDB
    -1. Get and install [couchdb](http://couchdb.apache.org/) 1.3.1 
    -2. Edit the local.ini to accept request from external host
    -
    -  `bind_address = 0.0.0.0`
    -  
    -  Also you may need to add appropriate firewall rules for port 5984.
    -  
    -  To test access to CouchDB portal try to open \<CouchDB host IP\>:5984 from browser
    -
    -  **Note:** don't use local IPs (e.g. localhost, 127.0.0.1) for CouchDB as it will produce
connection problems for devices and emulators (they will resolve them according to their context)
    -
    -3. Create the following three databases (functionality for creating of them should be
available on \<CouchDB host IP\>:5984/_utils/):
    -  - build_errors
    -  - mobilespec_results
    -  - test_details
    -
    -4. Add new document to `mobilespec_results` table with the following contents:
    -  ```
    -  {
    -      "_id": "_design/results",
    -      "views": {
    -          "sha": {
    -              "map": "function(doc){emit(doc.sha, {\"total\":doc.mobilespec.total,\"passed\":(doc.mobilespec.total
- doc.mobilespec.failed),\"version\":doc.version,\"model\":doc.model,\"fails\":doc.mobilespec.failures});}"
    -          }
    -      }
    -  }
    -  ```
    -
    -5. Set up a wireless access point so that the devices being tested can access the couchDB
    -
    -## Install BuildBot
    -1. Get [buildbot](http://buildbot.net) version 0.8.8
    -2. Install buildbot using the buildbot install/tutorial instructions
    -    http://docs.buildbot.net/latest/manual/installation.html
    -
    -    http://trac.buildbot.net/wiki/RunningBuildbotOnWindows
    -3. Get the sample running
    -4. Stop the slave and the master
    -5. Add slaves:
    -  - On Mac
    -    - buildslave create-slave slave_ios localhost:9889 cordova-ios-slave pass
    -    - buildslave create-slave slave_android localhost:9889 cordova-android-slave pass
    -  - On Windows
    -    - buildslave create-slave slave_windows localhost:9889 cordova-windows-slave pass
    - 
    -6. Copy the following files from the medic repository to buildbot master directory:
    -  - master.cfg
    -  - projects.conf
    -  - cordova.conf
    -  - cordova-repos.json
    -  - cordova-config.json.sample
    -
    -  Then update cordova-config.json.sample with CouchDB host address, test platforms, ios
keychain, current release build and _rename_ it to cordova-config.json
    -  
    -  **Note:** couchdb host must be specified via ip address due to windows platform restrictions.
    -
    -  **Note 2:** cordova-config.json and cordova-repos.json files should be placed near
cordova.conf (for local Medic instance in most cases this means that they need to be placed
in BuildBot master directory).
    -
    -#Running the System
    -- start the master with ~buildbot start master
    -- start the slaves with:
    -  - On Mac
    -    -  buildslave start slave_ios
    -    -  buildslave start slave_android
    -  - On Windows
    -    - buildslave start slave_windows
    -
    -    **Note:**  on Windows slave instance must be run under administrator; git/bin folder
must be added to PATH so that rm, cp, mkdir commands are available from the command prompt.
    -    
    -    **Note:**  if you are using Android emulator, please make sure that it has SD card
size bigger than 0 (see [CB-8535](https://issues.apache.org/jira/browse/CB-8535)).
    -- point your browser at http://localhost:8010/waterfall to see the buildbot state
    -- point your browser to the couchDB http://\<CouchDB host IP\>:5984/_utils/index.html
to look at detailed test results
    -
    -#Controlling
    -- restart the master with buildbot restart master
    -- stop the master with buildbot stop master
    -- force a test by clicking on the test link at the top of the buildbot display and then
'force build'
    -
    -#Configuring
    -- all changes for a local install should only require edits to cordova-config.json in
the buildbot base directory
    -- new platforms, test procedures, build steps, etc require edits to master.cfg, cordova.conf
and cordova-repos.json which should still be global (all platforms)
    -- whenever cordova-config.json, cordova-repos.json, cordova.conf or master.cfg changes,
you need to restart the master (not slaves)
    -
    -#Overview
    -Buildbot polls all the repositories every few minutes to look for changes. Whenever a
change is detected, those changes trigger one or more build requests. 
    -
    -Buildbot consists of a master that defines all the tests, the repositories, triggers,
etc.
    -The actual tests are run by slaves that are controlled by the master. The buildbot master
describes the steps to run for tests and which slaves those test should run on. 
    -Slaves that run tests on devices can only run one test at a time.
    -The common slave can run multiple tests at once.
    -
    -At the start of each test run, the collection of components (git repositories) and the
checked out SHA for each is collected into a document and written to the couchDB in test_details.

    -The DB ref from this document is used as the SHA for the test and is what is recorded
in mobilespec_results or build_errors
    -
    -The various test runners are configured to report a fail/pass by device and the buildbot
display will report FAIL if any test on any device fails. 
    -every command has a link to its output on the main display. When a mobile spec test completes,
there is a link to the test result written to the output log.
    -
    -#Current Test Configuration
    -- All slaves (Android, iOS, Windows) are configured to only run a single test at a time.
    -- Tools (Coho, CLI, test system) always build from the master branch
    -- Changes to tooling or the test scripts will trigger all tests.
    -
    -- Android tests:
    -  - platform, mobilespec, js, and plugins from master branch (cordova-js is built and
copied in)
    -  - platform and mobilspec 3.0.x branch with the cordova-js embedded in the cordova-android
repo, plugins from master
    -  - There are additional builder (AndroidWin), which perform builds of mobilespec application
for Android in Windows environment.
    -
    -- iOS tests:
    -  - platform, mobilespec, js, and plugins from master branch (cordova-js is built and
copied in)
    -  - platform and mobilspec 3.0.x branch with the cordova-js embedded in the cordova-ios
repo, plugins from master
    -
    -- Windows Phone8 tests:
    -  - platform, mobilespec, js, and plugins from master branch (cordova-js is built and
copied in).
    -  - There are two separate builders, which performs builds in different environments
(VS2012 + MSBuild 4.0 / VS2013 + MSBuild 12.0)
    -
    -- Windows Universal platform tests:
    -  - platform, mobilespec, js, and plugins from master branch (cordova-js is built and
copied in)
    -  - Tests are executed on Local Machine, mobilespec app for --phone target is launched
on emulator. Running mobilespec app on attached devices not supported yet.
    -  - There are two separate builders, which performs builds in different environments
(VS2012 + MSBuild 4.0 / VS2013 + MSBuild 12.0)
    -
    -The tests use COHO and CLI for as much as possible to ensure that the developer tool
chain is working.
    -
    -#Configuration Files
    -**master.cfg:** The main configuration file for buildbot. It is a python script and defines
the triggers, builders and status display.
    -It uses both cordova-config.json and cordova-repos.json to determine which platforms
and versions to test.
    -
    -**projects.conf** Configuration script used to load per-project buildbot configurations.
    -
    -**cordova.conf** Configuration script that contains cordova project-specific buldbot
configuration (Build steps, schedulers, build factories definitions, etc.)
    -
    -The two files above (_projects.conf_ and _cordova.conf_ are necessary to maintain compatibility
with Apache Buildbot configuration files structure)
    -
    -**cordova-config.json:** Used by the buildbot master script and by some of the medic
command-line tools. 
    -It defines the platforms to test, the current release version, the couchdb url, and the
ios keychain. 
    -The release version specified here is used anywhere the keyword "RELEASE" is used in
a test definition.
    -
    -**cordova-repos.json:** Contains the definitions for the tests (schedulers) and the various
repositories in the project. 
    -Tests define the components and branches that should trigger a test run. 
    -This requires multiple triggers for each test path since a build might use tools from
master, platforms from release and plugins from dev.
    -
    -For each repo there is a release branch (most recent supported release) and a current
branch (tip-of-tree). 
    -The branches are used by the python script in conjunction with the tests to set up the
trggers.
    +Cordova Medic
    +=============
    +
    +# Description
    +
    +This repository contains Buildbot configuration and automation tools for setting up a
continuous integration system for Apache Cordova. It currently supports builds on the following
platforms:
    +
    +- iOS
    +- Android (Windows and OS X)
    +- Windows Universal Apps (Windows 8.0, Windows 8.1, Windows Phone 8.1)
    +- Windows Phone 8
    +
    +# Prerequisites
    +
    +## CouchDB
    +
    +Medic depends on CouchDB for reporting results. The following steps document how to install
a CouchDB server for development. If a CouchDB server already exists for use, feel free to
skip to the Setting Up section.
    +
    +### Installation
    +
    +CouchDB can be installed from [this page][couchdb] as per the documentation provided
there. Once CouchDB is installed, configure it to accept requests from external hosts by setting
the following value in its `local.ini` file:
    +
    +    bind_address = 0.0.0.0
    +
    +Firewall rules for port 5984 (the default CouchDB port) may need to be added to allow
access to the server. To test that it is configured correctly, open `http://[COUCHDB_HOST]:5984/_utils/`
from a browser.
    +
    +### Setup
    +
    +Create the following databases:
    +
    +- build_errors
    +- test_details
    +- mobilespec_results
    +
    +They can be created by going to the CouchDB admin page (located at `http://[COUCHDB_HOST]:5984/_utils/`)
and clicking the `Create Database ...` button.
    +
    +Next, add the following document to the `mobilespec_results` database:
    +
    +    {
    +        "_id": "_design/results",
    +        "views": {
    +            "sha": {
    +                "map": "function(doc){emit(doc.sha, {\"total\":doc.mobilespec.total,\"passed\":(doc.mobilespec.total
- doc.mobilespec.failed),\"version\":doc.version,\"model\":doc.model,\"fails\":doc.mobilespec.failures});}"
    +            }
    +        }
    +    }
    +
    +Lastly, make sure that devices and machines that will be using Medic have access to the
Internet and to the CouchDB server that was just created.
    +
    +## Python
    +
    +Medic contains Python code and therefore requires Python. Install Python 2.7.x from [here][python].
*Do not install Python 3.x, because Medic does not run on it.* Make sure that the Python package
manager, pip, is installed with Python. To verify that Python and pip are installed, run the
following:
    +
    +    python --version
    +    pip --version
    +
    +On Windows, the PyWin32 extensions are required, and they can be acquired [here][pywin32].
    +
    +## Buildbot
    +
    +Medic uses Buildbot for running builds and performing continuous integration. Buildbot
has the concept of master and slave machines, and has different libraries for each. (More
info about Buildbot concepts can be found [here][bbconcepts]). To install the Buildbot library
for a master, run the following:
    +
    +    pip install buildbot
    +
    +For a machine that will run Buildbot slaves, install the Buildbot slave library by running
the following:
    +
    +    pip install buildbot-slave
    +
    +## UNIX tools
    +
    +To run builds, Medic slaves use some standard Unix tools such as `cp`, `rm`, and `git`.
To run them on Windows, install Git from [here][git] and make sure to select the option to
make basic Unix tools bundled with Git available within `cmd`.
    +
    +## Cordova
    +
    +Any core depencencies of Cordova, like Node.js and NPM, are naturally dependencies of
the slave machines that will run Cordova builds. Node.js and NPM can be obtained from [here][node].
    +
    +# Installation
    +
    +Medic contains configuration for a Buildbot installation to run Apache Cordova continuous
integration. Buildbot uses the master-slave paradigm to orchestrate builds, and medic contains
configuration for a Buildbot master and slaves, as well as a few extra files, all inside the
`buildbot-conf` directory.
    +
    +The instructions provided below describe a simple development setup, not a full-blown
production deployment, which is outside the scope of this document. More official documentation
on Buildbot can be found [here][buildbot], and on running Buildbot on Windows can be found
[here][buildbot_windows].
    +
    +Although a Buildbot master and slaves are separate tasks, they do not need to be run
on different machines, and the following steps can either be performed on separate machines
or the same one. Keep in mind however that a slave can only run builds that its machine's
environment supports.
    +
    +All of the following steps assume that Buildbot's slaves and masters will be installed
under `/home/buildbot`.
    +
    +## Master
    +
    +First, create a Buildbot master. The following steps are a summary of [these official
steps][buildmaster], so please feel free to follow the official ones instead.
    +
    +Create a master directory at `/home/buildbot/master` by running:
    +
    +    buildbot create-master /home/buildbot/master
    +
    +Then, install the Medic master configuration by copying the following files into `/home/buildbot/master`,
overwriting any files if prompted:
    +
    +- master.cfg
    +- projects.conf
    +- cordova.conf
    +- cordova-internal.conf
    +- cordova-repos.json
    +- *cordova-config.json*<sup>[1]</sup>
    +- *private.py*<sup>[1]</sup>
    +
    +<sup>[1]</sup> These two files do not exist in the repository and must be
created for each installation of Medic. Create them from their respective `.sample` files.
    +
    +## Slaves
    +
    +Now, create slaves. Similarly to the above instructions, the following steps are a summary
of [the official ones][buildslave], so please feel free to follow the official ones.
    +
    +On OS X:
    +
    +    buildslave create-slave /home/buildbot/osx http://[MASTER_HOST]:9889 cordova-ios-slave
pass
    +
    +On Linux:
    +
    +    buildslave create-slave /home/buildbot/linux http://[MASTER_HOST]:9889 cordova-linux-slave
pass
    +
    +On Windows 8 and Windows 8.1:
    +
    +    buildslave create-slave /home/buildbot/windows http://[MASTER_HOST]:9889 cordova-windows-slave
pass
    +
    +No further steps are necessary to make a slave obey a Medic master. However, every slave
needs to be configured appropriately for its platform. For platform-specific details on slave
configuration, see [SLAVES.md](SLAVES.md).
    +
    +# Running
    +
    +To start the master, run:
    +
    +    buildbot start /home/buildbot/master
    +
    +To start a slave (e.g. for Windows), run:
    +
    +    buildslave start /home/buildbot/windows
    +
    +To view the master control panel, browse the URI: `http://[MASTER_HOST]/`.
    +
    +To stop either task, just replace `start` with `stop` in the above commands. **NOTE**:
On Windows, the slave task blocks the console, and `Ctrl-C` will stop it. On all other platforms
both master and slave run as daemons, and using the `stop` command will terminate them.
    +
    +To check logs for a master or a slave, look at the `twistd.log` file in its respective
directory. Using the `tail` utility is very handy for this, like so:
    +
    +    tail -n 100 -f /home/buildbot/osx/twistd.log
    +
    +# Changing Configuration
    +
    +Buildbot has an unusual configuration mechanism (Python code) and as such requires a
restart to reload it. The Buildbot documentation also describes a  `buildbot reconfig` command,
but it does not work in all cases. More information is [here][reconfig].
    +
    +In general, when any of the files in the master directory are changed, a restart/reconfig
is necessary. However, slaves do not need to be reconfigured or restarted when the master's
configuration changes.
    +
    +# Configuration Layout
    --- End diff --
    
    Done.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org


Mime
View raw message