Skip to content
This repository

[docs] Added instructions for running unit/functional tests (batch and single w/ Arrow cmd) #610

Closed
wants to merge 16 commits into from

2 participants

Joe Catera username12
This page is out of date. Refresh to see the latest.

Showing 1 changed file with 171 additions and 1 deletion. Show diff stats Hide diff stats

  1. +171 1 docs/dev_guide/topics/mojito_testing.rst
172 docs/dev_guide/topics/mojito_testing.rst
Source Rendered
@@ -29,7 +29,6 @@ Conventions
29 29
30 30 { requires: [ 'mojito-test', 'HelloMojit' ] }
31 31
32   -
33 32 .. note:: Test files that are **not** in a ``tests`` directory may be found by Mojito as long as the
34 33 file name has the suffix ``-tests``. The suggested practice though is to place all test
35 34 files in the ``tests`` directories shown above.
@@ -510,7 +509,178 @@ the following commands:
510 509 - ``$ mojito test foo``
511 510 - ``$ mojito test foo-test``
512 511
  512 +.. _moj_tests-func_unit:
  513 +
  514 +Functional/Unit Tests
  515 +=====================
  516 +
  517 +Mojito comes with functional tests that you can run with the npm module
  518 +`Arrow <https://github.com/yahoo/arrow/>`_, a testing framework that fuses together JavaScript,
  519 +Node.js, PhantomJS, and Selenium. Arrow lets you write tests in
  520 +`YUI Test`_ that can be executed on the client or server.
  521 +You can also write your own functional/unit tests with Arrow. Mojito recommends that contributors
  522 +write Arrow functional/unit tests for their code to accelerate the process of merging pull requests.
  523 +
  524 +The following sections show you how to set up your environment and run the unit and
  525 +functional tests that come with Mojito. In the future, we will also provide you with instructions
  526 +for writing Arrow tests for your code contributions.
  527 +
  528 +.. _func_unit-builtin:
  529 +
  530 +Running Mojito's Built-In Tests
  531 +-------------------------------
  532 +
  533 +.. _func_unit-reqs:
  534 +
  535 +Required Software
  536 +#################
  537 +
  538 +- `Java <http://www.java.com/en/download/manual.jsp>`_
  539 +- `Node.js 0.6 or higher (packaged with npm) <http://nodejs.org/>`_
  540 +- `Git <http://git-scm.com/downloads>`_
  541 +
  542 +.. _func_unit_reqs-macs:
  543 +
  544 +Macs
  545 +####
  546 +
  547 +.. _func_unit-macs_setup:
  548 +
  549 +Setting Up
  550 +~~~~~~~~~~
513 551
  552 +#. `Download PhantomJS <http://www.doctor46.com/phantomjs>`_.
  553 +#. Copy the phantomjs binary to ``/usr/local/bin/``.
  554 +
  555 + ``$ cp phantomjs /usr/local/bin/``
  556 +#. Install Arrow:
  557 +
  558 + ``$ npm install yahoo-arrow -g``
  559 +#. Start the Arrow server to confirm it was installed:
  560 +
  561 + ``$ arrow_server``
  562 +#. Shut down the Arrow server with ``Ctrl-C^`` command.
  563 +
  564 +.. _func_unit_reqs-linux:
  565 +
  566 +Linux
  567 +#####
  568 +
  569 +.. _func_unit-linux_setup:
  570 +
  571 +Setting Up
  572 +~~~~~~~~~~
  573 +
  574 +#. Follow the `installation instructions for PhantomJS <http://www.doctor46.com/phantomjs>`_.
  575 +#. Copy the phantomjs binary to ``/usr/local/bin/``.
  576 +#. Install Arrow:
  577 +
  578 + ``$ npm install yahoo-arrow -g``
  579 +#. Start the Arrow server to confirm it was installed:
  580 +
  581 + ``$ arrow_server``
  582 +#. Shut down the Arrow server with ``Ctrl-C^`` command.
  583 +
  584 +
  585 +.. _func_unit-install_selenium:
  586 +
  587 +Installing Selenium (recommended)
  588 +#################################
  589 +
  590 +The following instructions work for both Macs and Linux.
  591 +
  592 +#. `Download the Selenium JAR executable <http://selenium.googlecode.com/files/selenium-server-standalone-2.22.0.jar>`_.
  593 +#. Start the Selenium server:
  594 +
  595 + ``$ java -jar path/to/selenium-server.jar``
  596 +#. Confirm Selenium is running by going to the following URL:
  597 +
  598 + `http://localhost:4444/wd/hub/static/resource/hub.html <http://localhost:4444/wd/hub/static/resource/hub.html>`_
  599 +#. Shut down the Selenium server with ``Ctrl-C^`` command.
  600 +
  601 +.. _func_unit-run:
  602 +
  603 +Running Tests
  604 +#############
  605 +
  606 +.. _func_unit_run-batch:
  607 +
  608 +Running Batch Tests
  609 +~~~~~~~~~~~~~~~~~~~
  610 +
  611 +The following instructions show you how to run Arrow tests with the wrapper script ``run.js``,
  612 +which allows you to run batch tests. For example, you can use ``run.js`` to run all of the Mojito
  613 +functional or unit tests with one command.
  614 +
  615 +#. Clone the Mojito repository.
  616 +
  617 + ``$ git clone https://github.com/yahoo/mojito.git``
  618 +#. Change to the ``mojito`` directory.
  619 +#. Install Mojito's dependencies. Mojito needs several npm modules to
  620 + run tests.
  621 +
  622 + ``$ npm install``
  623 +#. Change to the ``tests`` directory.
  624 +#. Start the Selenium server in the background.
  625 +
  626 + ``$ java -jar path/to/selenium-server.jar &``
  627 +#. Run the unit tests for the framework and client:
  628 +
  629 + ``$ ./run.js test -u --group fw,client,server``
  630 +#. You can also run all the functional tests with the below command. The functional tests
  631 + may take some time to complete, so you may want to terminate the tests with **Ctl-C**.
  632 +
  633 + ``$ ./run.js test -f``
  634 +#. To view the test reports (in JSON or XML) in the following directories:
  635 +
  636 + - ``$ ./unit/artifacts/arrowreport/``
  637 + - ``$ ./func/artifacts/arrowreport/``
  638 +
  639 +.. note:: You will not get a report if you terminated any tests before they completed.
  640 + Also, Selenium will display the error message ``SeleniumDriver - Failed to collect the
  641 + test report`` if a previously generated report exists.
  642 +
  643 +
  644 +.. _func_unit_run-arrow:
  645 +
  646 +Using Arrow to Run Tests
  647 +~~~~~~~~~~~~~~~~~~~~~~~~
  648 +
  649 +You can also separately run unit and functional tests directly
  650 +with the ``arrow`` command. You pass Arrow a test descriptor, which
  651 +is a JSON configuration file that describes and organizes your tests.
  652 +For an overview of Arrow and the command-line options, see
  653 +the `Arrow README <https://github.com/yahoo/arrow/blob/master/README.md>`_.
  654 +
  655 +In the following steps, you'll start a routing application, run a test with Arrow,
  656 +and then look at the test reports. Afterward, you should be able to
  657 +run some of the other tests included with Mojito.
  658 +
  659 +#. Start Selenium in the background if it is not running already. You can confirm that it's running
  660 + by going to http://127.0.0.1:4444/wd/hub/static/resource/hub.html.
  661 +#. Change to the directory containing the routing test application.
  662 +
  663 + ``$ cd mojito/tests/func/applications/frameworkapp/routing``
  664 +#. Start the application specifying port 4082 in the background.
  665 +
  666 + ``$ mojito start 4082 &``
  667 +#. Change to the directory containing the tests for the routing applications.
  668 +
  669 + ``$ cd mojito/tests/func/routing``
  670 +#. Launch Firefox with ``arrow_selenium``.
  671 +
  672 + ``$ arrow_selenium --open=firefox``
  673 +#. After Firefox has launched, run the functional routing tests with Arrow with the ``arrow`` command,
  674 + the test descriptor, and the option ``--browser=reuse``:
  675 +
  676 + ``$ arrow routingtest_descriptor.json --browser=reuse``
  677 +#. You should see the functional tests running in Firefox testing different routing paths.
  678 +#. As with running the ``run.js`` script, Arrow will generate reports containing
  679 + the results of the tests, but the report names will match the name of the
  680 + test descriptor and be located in the current working directory. Thus,
  681 + you should see the test reports ``routingtest_descriptor-report.json`` and
  682 + ``routingtest_descriptor-report.xml``.
  683 +
514 684
515 685 .. _YUI Test: http://yuilibrary.com/yuitest/
516 686

Tip: You can add notes to lines in a file. Hover to the left of a line to make a note

Something went wrong with that request. Please try again.