poolparty 0.2.18 → 0.2.69
Sign up to get free protection for your applications and to get access to all the features.
- data/Manifest.txt +142 -47
- data/PostInstall.txt +5 -5
- data/README.txt +25 -4
- data/Rakefile +46 -2
- data/bin/cloud +12 -21
- data/bin/cloud-add-keypair +18 -13
- data/bin/cloud-configure +11 -18
- data/bin/cloud-contract +7 -17
- data/bin/cloud-ensure-provisioning +39 -0
- data/bin/cloud-expand +9 -17
- data/bin/cloud-handle-load +27 -0
- data/bin/cloud-list +3 -9
- data/bin/cloud-maintain +12 -18
- data/bin/cloud-osxcopy +3 -9
- data/bin/cloud-provision +20 -21
- data/bin/cloud-refresh +4 -13
- data/bin/cloud-run +3 -4
- data/bin/cloud-ssh +3 -2
- data/bin/cloud-start +18 -21
- data/bin/cloud-stats +17 -0
- data/bin/cloud-terminate +4 -7
- data/bin/messenger-get-current-nodes +14 -0
- data/bin/pool +12 -12
- data/bin/pool-describe +0 -1
- data/bin/{pool-spec → pool-generate} +1 -0
- data/bin/pool-init +28 -0
- data/bin/pool-list +14 -12
- data/bin/pool-start +11 -17
- data/bin/server-build-messenger +13 -6
- data/bin/server-fire-cmd +1 -1
- data/bin/server-get-load +5 -16
- data/bin/server-list-active +3 -10
- data/bin/server-rerun +4 -4
- data/bin/server-send-command +18 -0
- data/bin/server-show-stats +17 -0
- data/bin/server-start-client +29 -0
- data/bin/server-start-master +13 -14
- data/bin/server-start-node +14 -15
- data/bin/server-stop-client +3 -0
- data/bin/server-stop-master +3 -0
- data/bin/server-stop-node +3 -0
- data/bin/server-update-hosts +48 -0
- data/config/hoe.rb +4 -3
- data/examples/plugin_without_plugin_directory.rb +1 -2
- data/generators/poolspec/USAGE +2 -2
- data/generators/poolspec/poolspec_generator.rb +2 -1
- data/generators/poolspec/templates/pool_spec_template.erb +3 -2
- data/lib/erlang/messenger/Rakefile +12 -0
- data/lib/erlang/messenger/ebin/client.app +19 -0
- data/lib/erlang/messenger/ebin/master.app +1 -1
- data/lib/erlang/messenger/ebin/node.app +1 -1
- data/lib/erlang/messenger/ebin/pm_client_rel-0.1.rel +1 -0
- data/lib/erlang/messenger/ebin/pm_master_rel-0.1.rel +1 -1
- data/lib/erlang/messenger/ebin/pm_node_rel-0.1.rel +1 -1
- data/lib/erlang/messenger/include/defines.hrl +27 -0
- data/lib/erlang/messenger/lib/eunit/.svn/all-wcprops +53 -0
- data/lib/erlang/messenger/lib/eunit/.svn/entries +140 -0
- data/lib/erlang/messenger/lib/eunit/.svn/format +1 -0
- data/lib/erlang/messenger/lib/eunit/.svn/prop-base/NOTES.svn-base +5 -0
- data/lib/erlang/messenger/lib/eunit/.svn/text-base/AUTHORS.svn-base +2 -0
- data/lib/erlang/messenger/lib/eunit/.svn/text-base/CHANGELOG.svn-base +14 -0
- data/lib/erlang/messenger/lib/eunit/.svn/text-base/COPYING.svn-base +504 -0
- data/lib/erlang/messenger/lib/eunit/.svn/text-base/NOTES.svn-base +276 -0
- data/lib/erlang/messenger/lib/eunit/.svn/text-base/README.svn-base +3 -0
- data/lib/erlang/messenger/lib/eunit/.svn/text-base/sys.config.svn-base +9 -0
- data/lib/erlang/messenger/lib/eunit/.svn/text-base/vsn.mk.svn-base +1 -0
- data/lib/erlang/messenger/lib/eunit/doc/.svn/all-wcprops +59 -0
- data/lib/erlang/messenger/lib/eunit/doc/.svn/entries +142 -0
- data/lib/erlang/messenger/lib/eunit/doc/.svn/format +1 -0
- data/lib/erlang/messenger/lib/eunit/doc/.svn/prop-base/erlang.png.svn-base +5 -0
- data/lib/erlang/messenger/lib/eunit/doc/.svn/prop-base/eunit.html.svn-base +5 -0
- data/lib/erlang/messenger/lib/eunit/doc/.svn/prop-base/index.html.svn-base +5 -0
- data/lib/erlang/messenger/lib/eunit/doc/.svn/prop-base/modules-frame.html.svn-base +5 -0
- data/lib/erlang/messenger/lib/eunit/doc/.svn/prop-base/overview-summary.html.svn-base +5 -0
- data/lib/erlang/messenger/lib/eunit/doc/.svn/prop-base/packages-frame.html.svn-base +5 -0
- data/lib/erlang/messenger/lib/eunit/doc/.svn/text-base/edoc-info.svn-base +3 -0
- data/lib/erlang/messenger/lib/eunit/doc/.svn/text-base/erlang.png.svn-base +0 -0
- data/lib/erlang/messenger/lib/eunit/doc/.svn/text-base/eunit.html.svn-base +172 -0
- data/lib/erlang/messenger/lib/eunit/doc/.svn/text-base/index.html.svn-base +17 -0
- data/lib/erlang/messenger/lib/eunit/doc/.svn/text-base/modules-frame.html.svn-base +12 -0
- data/lib/erlang/messenger/lib/eunit/doc/.svn/text-base/overview-summary.html.svn-base +984 -0
- data/lib/erlang/messenger/lib/eunit/doc/.svn/text-base/overview.edoc.svn-base +980 -0
- data/lib/erlang/messenger/lib/eunit/doc/.svn/text-base/packages-frame.html.svn-base +11 -0
- data/lib/erlang/messenger/lib/eunit/doc/.svn/text-base/stylesheet.css.svn-base +55 -0
- data/lib/erlang/messenger/lib/eunit/ebin/.svn/all-wcprops +5 -0
- data/lib/erlang/messenger/lib/eunit/ebin/.svn/dir-prop-base +8 -0
- data/lib/erlang/messenger/lib/eunit/ebin/.svn/entries +28 -0
- data/lib/erlang/messenger/lib/eunit/ebin/.svn/format +1 -0
- data/lib/erlang/messenger/lib/eunit/examples/.svn/all-wcprops +23 -0
- data/lib/erlang/messenger/lib/eunit/examples/.svn/entries +66 -0
- data/lib/erlang/messenger/lib/eunit/examples/.svn/format +1 -0
- data/lib/erlang/messenger/lib/eunit/examples/.svn/prop-base/eunit_examples.erl.svn-base +5 -0
- data/lib/erlang/messenger/lib/eunit/examples/.svn/prop-base/fib.erl.svn-base +5 -0
- data/lib/erlang/messenger/lib/eunit/examples/.svn/text-base/eunit_examples.erl.svn-base +339 -0
- data/lib/erlang/messenger/lib/eunit/examples/.svn/text-base/fib.erl.svn-base +19 -0
- data/lib/erlang/messenger/lib/eunit/examples/.svn/text-base/tests.txt.svn-base +1 -0
- data/lib/erlang/messenger/lib/eunit/include/.svn/all-wcprops +11 -0
- data/lib/erlang/messenger/lib/eunit/include/.svn/entries +41 -0
- data/lib/erlang/messenger/lib/eunit/include/.svn/format +1 -0
- data/lib/erlang/messenger/lib/eunit/include/.svn/prop-base/eunit.hrl.svn-base +5 -0
- data/lib/erlang/messenger/lib/eunit/include/.svn/text-base/eunit.hrl.svn-base +313 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/all-wcprops +113 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/entries +259 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/format +1 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/prop-base/autoload.erl.svn-base +5 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/prop-base/code_monitor.erl.svn-base +5 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/prop-base/eunit.erl.svn-base +5 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/prop-base/eunit_autoexport.erl.svn-base +5 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/prop-base/eunit_data.erl.svn-base +5 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/prop-base/eunit_internal.hrl.svn-base +5 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/prop-base/eunit_lib.erl.svn-base +5 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/prop-base/eunit_proc.erl.svn-base +5 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/prop-base/eunit_serial.erl.svn-base +5 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/prop-base/eunit_server.erl.svn-base +5 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/prop-base/eunit_striptests.erl.svn-base +5 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/prop-base/eunit_test.erl.svn-base +5 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/prop-base/eunit_tests.erl.svn-base +5 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/prop-base/eunit_tty.erl.svn-base +5 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/prop-base/file_monitor.erl.svn-base +5 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/text-base/autoload.erl.svn-base +388 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/text-base/code_monitor.erl.svn-base +243 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/text-base/eunit.app.src.svn-base +21 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/text-base/eunit.appup.src.svn-base +1 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/text-base/eunit.erl.svn-base +196 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/text-base/eunit_autoexport.erl.svn-base +102 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/text-base/eunit_data.erl.svn-base +798 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/text-base/eunit_internal.hrl.svn-base +48 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/text-base/eunit_lib.erl.svn-base +682 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/text-base/eunit_proc.erl.svn-base +552 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/text-base/eunit_serial.erl.svn-base +157 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/text-base/eunit_server.erl.svn-base +340 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/text-base/eunit_striptests.erl.svn-base +64 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/text-base/eunit_test.erl.svn-base +334 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/text-base/eunit_tests.erl.svn-base +45 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/text-base/eunit_tty.erl.svn-base +272 -0
- data/lib/erlang/messenger/lib/eunit/src/.svn/text-base/file_monitor.erl.svn-base +409 -0
- data/lib/erlang/messenger/pm_client_rel-0.1.boot +0 -0
- data/lib/erlang/messenger/pm_client_rel-0.1.script +238 -0
- data/lib/erlang/messenger/pm_master_rel-0.1.boot +0 -0
- data/lib/erlang/messenger/pm_master_rel-0.1.script +82 -85
- data/lib/erlang/messenger/pm_node_rel-0.1.boot +0 -0
- data/lib/erlang/messenger/pm_node_rel-0.1.script +80 -85
- data/lib/erlang/messenger/src/client_app.erl +39 -0
- data/lib/erlang/messenger/src/client_server.erl +60 -0
- data/lib/erlang/messenger/src/pm_client.erl +48 -18
- data/lib/erlang/messenger/src/pm_client_old.erl +52 -0
- data/lib/erlang/messenger/src/pm_client_supervisor.erl +38 -0
- data/lib/erlang/messenger/src/pm_cluster.erl +20 -16
- data/lib/erlang/messenger/src/pm_event_manager.erl +27 -0
- data/lib/erlang/messenger/src/pm_master.erl +126 -34
- data/lib/erlang/messenger/src/pm_master_event_handler.erl +72 -0
- data/lib/erlang/messenger/src/pm_master_supervisor.erl +9 -10
- data/lib/erlang/messenger/src/pm_node.erl +107 -30
- data/lib/erlang/messenger/src/pm_node_supervisor.erl +13 -15
- data/lib/erlang/messenger/src/pm_packager.erl +5 -2
- data/lib/erlang/messenger/src/pm_strings.erl +11 -0
- data/lib/erlang/messenger/src/utils.erl +43 -8
- data/lib/erlang/messenger/useful_snippets +17 -0
- data/lib/poolparty/aska/aska.rb +150 -0
- data/lib/poolparty/base_packages/haproxy.rb +19 -26
- data/lib/poolparty/base_packages/heartbeat.rb +48 -47
- data/lib/poolparty/base_packages/poolparty.rb +88 -36
- data/lib/poolparty/base_packages/runit.rb +21 -0
- data/lib/poolparty/config/postlaunchmessage.txt +5 -0
- data/lib/poolparty/core/array.rb +4 -1
- data/lib/poolparty/core/class.rb +2 -0
- data/lib/poolparty/core/exception.rb +2 -1
- data/lib/poolparty/core/hash.rb +2 -2
- data/lib/poolparty/core/kernel.rb +3 -3
- data/lib/poolparty/core/metaid.rb +15 -0
- data/lib/poolparty/core/object.rb +42 -2
- data/lib/poolparty/core/string.rb +21 -6
- data/lib/poolparty/core/symbol.rb +9 -0
- data/lib/poolparty/dependency_resolutions/puppet.rb +20 -7
- data/lib/poolparty/exceptions/CloudNotFoundException.rb +7 -0
- data/lib/poolparty/exceptions/LoadRulesException.rb +7 -0
- data/lib/poolparty/exceptions/MasterException.rb +10 -0
- data/lib/poolparty/helpers/binary.rb +37 -4
- data/lib/poolparty/helpers/console.rb +25 -8
- data/lib/poolparty/helpers/nice_printer.rb +36 -0
- data/lib/poolparty/helpers/optioner.rb +51 -16
- data/lib/poolparty/helpers/provisioner_base.rb +117 -28
- data/lib/poolparty/helpers/provisioners/master.rb +102 -35
- data/lib/poolparty/helpers/provisioners/slave.rb +25 -9
- data/lib/poolparty/modules/cloud_dsl.rb +13 -0
- data/lib/poolparty/modules/cloud_resourcer.rb +51 -8
- data/lib/poolparty/modules/configurable.rb +1 -1
- data/lib/poolparty/modules/definable_resource.rb +2 -2
- data/lib/poolparty/modules/file_writer.rb +37 -6
- data/lib/poolparty/modules/method_missing_sugar.rb +8 -3
- data/lib/poolparty/modules/pretty_printer.rb +1 -0
- data/lib/poolparty/modules/resourcing_dsl.rb +4 -2
- data/lib/poolparty/modules/thread_pool.rb +106 -0
- data/lib/poolparty/monitors/base_monitor.rb +65 -6
- data/lib/poolparty/monitors/monitors/cpu_monitor.rb +1 -1
- data/lib/poolparty/monitors/monitors/memory_monitor.rb +28 -1
- data/lib/poolparty/monitors/monitors/web_monitor.rb +18 -0
- data/lib/poolparty/net/messenger.rb +72 -0
- data/lib/poolparty/net/remote.rb +5 -2
- data/lib/poolparty/net/remote_bases/ec2/ec2_response_object.rb +66 -0
- data/lib/poolparty/net/remote_bases/ec2.rb +133 -131
- data/lib/poolparty/net/remote_instance.rb +28 -6
- data/lib/poolparty/net/remoter.rb +117 -64
- data/lib/poolparty/net/remoter_base.rb +49 -11
- data/lib/poolparty/plugins/deploydirectory.rb +66 -0
- data/lib/poolparty/plugins/line.rb +5 -4
- data/lib/poolparty/plugins/rsyncmirror.rb +26 -0
- data/lib/poolparty/plugins/runit.rb +96 -0
- data/lib/poolparty/plugins/svn.rb +1 -1
- data/lib/poolparty/pool/base.rb +47 -18
- data/lib/poolparty/pool/cloud.rb +121 -65
- data/lib/poolparty/pool/custom_resource.rb +4 -20
- data/lib/poolparty/pool/loggable.rb +3 -8
- data/lib/poolparty/pool/plugin.rb +14 -19
- data/lib/poolparty/pool/plugin_model.rb +8 -8
- data/lib/poolparty/pool/pool.rb +28 -11
- data/lib/poolparty/pool/resource.rb +109 -40
- data/lib/poolparty/pool/resources/class_package.rb +74 -33
- data/lib/poolparty/pool/resources/conditional.rb +32 -10
- data/lib/poolparty/pool/resources/custom_service.rb +30 -0
- data/lib/poolparty/pool/resources/exec.rb +6 -5
- data/lib/poolparty/pool/resources/gem_package.rb +52 -0
- data/lib/poolparty/pool/resources/mount.rb +22 -0
- data/lib/poolparty/pool/resources/package.rb +13 -3
- data/lib/poolparty/pool/resources/sshkey.rb +1 -1
- data/lib/poolparty/pool/resources/variable.rb +4 -0
- data/lib/poolparty/pool/script.rb +8 -6
- data/lib/poolparty/templates/haproxy.conf +1 -1
- data/lib/poolparty/templates/messenger/client/log-run.erb +2 -0
- data/lib/poolparty/templates/messenger/client/run.erb +4 -0
- data/lib/poolparty/templates/messenger/master/log-run.erb +2 -0
- data/lib/poolparty/templates/messenger/master/run.erb +4 -0
- data/lib/poolparty/templates/messenger/node/log-run.erb +2 -0
- data/lib/poolparty/templates/messenger/node/run.erb +4 -0
- data/lib/poolparty/templates/poolparty.monitor +1 -1
- data/lib/poolparty/templates/puppet.conf +0 -0
- data/lib/poolparty/templates/puppetcleaner +6 -0
- data/lib/poolparty/templates/puppetrerun +9 -0
- data/lib/poolparty/templates/puppetrunner +8 -0
- data/lib/poolparty/templates/yaws.conf +19 -0
- data/lib/poolparty/version.rb +1 -1
- data/lib/poolparty.rb +35 -6
- data/lib/poolpartycl.rb +4 -0
- data/log/pool.logs +0 -0
- data/poolparty.gemspec +574 -61
- data/spec/poolparty/aska/aska_spec.rb +122 -0
- data/spec/poolparty/bin/console_spec.rb +18 -0
- data/spec/poolparty/core/hash_spec.rb +4 -4
- data/spec/poolparty/core/object_spec.rb +29 -0
- data/spec/poolparty/core/string_spec.rb +6 -0
- data/spec/poolparty/core/time_spec.rb +0 -3
- data/spec/poolparty/helpers/binary_spec.rb +2 -2
- data/spec/poolparty/helpers/optioner_spec.rb +1 -4
- data/spec/poolparty/helpers/provisioner_base_spec.rb +14 -1
- data/spec/poolparty/helpers/provisioners/master_spec.rb +3 -3
- data/spec/poolparty/modules/cloud_resourcer_spec.rb +3 -3
- data/spec/poolparty/modules/configurable_spec.rb +4 -1
- data/spec/poolparty/monitors/base_monitor_spec.rb +94 -2
- data/spec/poolparty/monitors/monitors/cpu_monitor_spec.rb +0 -1
- data/spec/poolparty/monitors/monitors/memory_monitor_spec.rb +47 -0
- data/spec/poolparty/{helpers → net}/messenger_spec.rb +3 -1
- data/spec/poolparty/net/remote_bases/ec2_spec.rb +46 -5
- data/spec/poolparty/net/remote_instance_spec.rb +2 -1
- data/spec/poolparty/net/remote_spec.rb +30 -8
- data/spec/poolparty/net/remoter_base_spec.rb +4 -1
- data/spec/poolparty/net/remoter_spec.rb +11 -108
- data/spec/poolparty/plugins/deploydirectory_spec.rb +51 -0
- data/spec/poolparty/pool/base_spec.rb +43 -33
- data/spec/poolparty/pool/cloud_spec.rb +299 -248
- data/spec/poolparty/pool/custom_resource_spec.rb +10 -5
- data/spec/poolparty/pool/example_spec.rb +0 -84
- data/spec/poolparty/pool/plugin_model_spec.rb +3 -2
- data/spec/poolparty/pool/plugin_spec.rb +89 -62
- data/spec/poolparty/pool/pool_spec.rb +17 -2
- data/spec/poolparty/pool/resource_spec.rb +341 -236
- data/spec/poolparty/pool/resources/class_package_spec.rb +102 -66
- data/spec/poolparty/pool/resources/conditional_spec.rb +65 -26
- data/spec/poolparty/pool/resources/cron_spec.rb +3 -2
- data/spec/poolparty/pool/resources/exec_spec.rb +1 -1
- data/spec/poolparty/pool/resources/gem_spec.rb +18 -14
- data/spec/poolparty/pool/resources/remote_file_spec.rb +1 -1
- data/spec/poolparty/pool/resources/variable_spec.rb +1 -1
- data/spec/poolparty/pool/script_spec.rb +58 -37
- data/spec/poolparty/pool/test_plugins/webserver.rb +1 -0
- data/spec/poolparty/spec_helper.rb +16 -5
- data/tasks/deployment.rake +19 -3
- data/tasks/development.rake +11 -2
- data/tasks/ec2.rake +9 -1
- data/website/index.html +2 -2
- metadata +167 -70
- data/bin/pool-provision +0 -34
- data/erl_crash.dump +0 -8409
- data/examples/with_apache_plugin.rb +0 -22
- data/lib/erlang/messenger/Makefile +0 -15
- data/lib/erlang/messenger/ebin/master_app.beam +0 -0
- data/lib/erlang/messenger/ebin/node_app.beam +0 -0
- data/lib/erlang/messenger/ebin/pm_client.beam +0 -0
- data/lib/erlang/messenger/ebin/pm_cluster.beam +0 -0
- data/lib/erlang/messenger/ebin/pm_event_handler.beam +0 -0
- data/lib/erlang/messenger/ebin/pm_master.beam +0 -0
- data/lib/erlang/messenger/ebin/pm_master_supervisor.beam +0 -0
- data/lib/erlang/messenger/ebin/pm_node.beam +0 -0
- data/lib/erlang/messenger/ebin/pm_node_supervisor.beam +0 -0
- data/lib/erlang/messenger/ebin/pm_packager.beam +0 -0
- data/lib/erlang/messenger/ebin/utils.beam +0 -0
- data/lib/erlang/messenger/lib/eunit/Makefile +0 -28
- data/lib/erlang/messenger/lib/eunit/ebin/autoload.beam +0 -0
- data/lib/erlang/messenger/lib/eunit/ebin/code_monitor.beam +0 -0
- data/lib/erlang/messenger/lib/eunit/ebin/eunit.beam +0 -0
- data/lib/erlang/messenger/lib/eunit/ebin/eunit_autoexport.beam +0 -0
- data/lib/erlang/messenger/lib/eunit/ebin/eunit_data.beam +0 -0
- data/lib/erlang/messenger/lib/eunit/ebin/eunit_lib.beam +0 -0
- data/lib/erlang/messenger/lib/eunit/ebin/eunit_proc.beam +0 -0
- data/lib/erlang/messenger/lib/eunit/ebin/eunit_serial.beam +0 -0
- data/lib/erlang/messenger/lib/eunit/ebin/eunit_server.beam +0 -0
- data/lib/erlang/messenger/lib/eunit/ebin/eunit_striptests.beam +0 -0
- data/lib/erlang/messenger/lib/eunit/ebin/eunit_test.beam +0 -0
- data/lib/erlang/messenger/lib/eunit/ebin/eunit_tests.beam +0 -0
- data/lib/erlang/messenger/lib/eunit/ebin/eunit_tty.beam +0 -0
- data/lib/erlang/messenger/lib/eunit/ebin/file_monitor.beam +0 -0
- data/lib/erlang/messenger/lib/eunit/src/Makefile +0 -46
- data/lib/erlang/messenger/src/pm_event_handler.erl +0 -21
- data/lib/poolparty/config/allowed_commands.yml +0 -1
- data/lib/poolparty/helpers/messenger.rb +0 -29
- data/lib/poolparty/plugins/git.rb +0 -39
- data/lib/poolparty/pool/resources/gem.rb +0 -28
- data/lib/poolparty/pool/tmp/.ppkeys +0 -3
- data/lib/poolparty/pool/tmp/happydayz +0 -1
- data/lib/poolparty/pool/tmp/install_master.sh +0 -33
- data/lib/poolparty/pool/tmp/pool.spec +0 -11
- data/lib/poolparty/pool/tmp/poolparty.pp +0 -600
- data/lib/poolparty/pool/tmp/tc-instances.list +0 -1
- data/lib/poolparty/templates/fileserver.conf +0 -4
- data/spec/poolparty/plugins/git_spec.rb +0 -33
- data/test_manifest.pp +0 -658
@@ -0,0 +1,984 @@
|
|
1
|
+
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
2
|
+
<html>
|
3
|
+
<head>
|
4
|
+
<title>EUnit - a Lightweight Unit Testing Framework for Erlang
|
5
|
+
</title>
|
6
|
+
<link rel="stylesheet" type="text/css" href="stylesheet.css" title="EDoc">
|
7
|
+
</head>
|
8
|
+
<body bgcolor="white">
|
9
|
+
<div class="navbar"><a name="#navbar_top"></a><table width="100%" border="0" cellspacing="0" cellpadding="2" summary="navigation bar"><tr><td><a href="overview-summary.html" target="overviewFrame">Overview</a></td><td><a href="http://www.erlang.org/"><img src="erlang.png" align="right" border="0" alt="erlang logo"></a></td></tr></table></div>
|
10
|
+
<h1>EUnit - a Lightweight Unit Testing Framework for Erlang
|
11
|
+
</h1>
|
12
|
+
<p>Copyright � 2004-2007 Micka�l R�mond, Richard Carlsson</p>
|
13
|
+
<p><b>Version:</b> 2.0 beta 1, Oct 12 2008 14:17:27
|
14
|
+
</p>
|
15
|
+
<p><b>Authors:</b> Richard Carlsson (<a href="mailto:richardc@it.uu.se"><tt>richardc@it.uu.se</tt></a>) [<em>web site:</em> <tt><a href="http://user.it.uu.se/~richardc/" target="_top">http://user.it.uu.se/~richardc/</a></tt>], Micka�l R�mond (<a href="mailto:mickael.remond@process-one.net"><tt>mickael.remond@process-one.net</tt></a>) [<em>web site:</em> <tt><a href="http://www.process-one.net/" target="_top">http://www.process-one.net/</a></tt>].</p>
|
16
|
+
<p>EUnit is a unit testing framework for Erlang. It is very powerful
|
17
|
+
and flexible, is easy to use, and has small syntactical overhead.</p>
|
18
|
+
|
19
|
+
<ul>
|
20
|
+
<li><a href="#Unit_Testing">Unit Testing</a></li>
|
21
|
+
<li><a href="#Terminology">Terminology</a></li>
|
22
|
+
<li><a href="#Getting_started">Getting started</a></li>
|
23
|
+
<li><a href="#EUnit_macros">EUnit macros</a></li>
|
24
|
+
<li><a href="#EUnit_test_representation">EUnit test representation</a></li>
|
25
|
+
</ul>
|
26
|
+
|
27
|
+
<p>EUnit builds on ideas from the family of unit testing frameworks for
|
28
|
+
Object Oriented languages that originated with JUnit by Beck and Gamma
|
29
|
+
(and Beck's previous framework SUnit for Smalltalk). However, EUnit uses
|
30
|
+
techniques more adapted to functional and concurrent programming, and is
|
31
|
+
typically less verbose than its relatives.</p>
|
32
|
+
|
33
|
+
<p>Although EUnit uses many preprocessor macros, they have been designed to
|
34
|
+
be as nonintrusive as possible, and should not cause conflicts with
|
35
|
+
existing code. Adding EUnit tests to a module should thus not normally
|
36
|
+
require modifying code. Furthermore, tests that only exercise the
|
37
|
+
exported functions of a module can always be placed in a completely
|
38
|
+
separate module, avoiding any conflicts entirely.</p>
|
39
|
+
|
40
|
+
<h3><a name="Unit_Testing">Unit Testing</a></h3>
|
41
|
+
|
42
|
+
<p>Unit Testing is testing of individual program "units" in relative
|
43
|
+
isolation. There is no particular size requirement: a unit can be a
|
44
|
+
function, a module, a process, or even a whole application, but the most
|
45
|
+
typical testing units are individual functions or modules. In order to
|
46
|
+
test a unit, you specify a set of individual tests, set up the smallest
|
47
|
+
necessary environment for being able to run those tests (often, you
|
48
|
+
don't need to do any setup at all), you run the tests and collect the
|
49
|
+
results, and finally you do any necessary cleanup so that the test can
|
50
|
+
be run again later. A Unit Testing Framework tries to help you in each
|
51
|
+
stage of this process, so that it is easy to write tests, easy to run
|
52
|
+
them, and easy to see which tests failed (so you can fix the bugs).</p>
|
53
|
+
|
54
|
+
<h4><a name="Advantages_of_unit_testing">Advantages of unit testing</a></h4>
|
55
|
+
|
56
|
+
<dl>
|
57
|
+
<dt>Reduces the risks of changing the program</dt>
|
58
|
+
<dd>Most programs will be modified during their lifetime: bugs will be
|
59
|
+
fixed, features will be added, optimizations may become necessary, or
|
60
|
+
the code will need to be refactored or cleaned up in other ways to
|
61
|
+
make it easier to work with. But every change to a working program is
|
62
|
+
a risk of introducing new bugs - or reintroducing bugs that had
|
63
|
+
previously been fixed. Having a set of unit tests that you can run
|
64
|
+
with very little effort makes it easy to know that the code still
|
65
|
+
works as it should (this use is called <em>regression testing</em>;
|
66
|
+
see <a href="#Terminology">Terminology</a>). This goes a long way to reduce the
|
67
|
+
resistance to changing and refactoring code.</dd>
|
68
|
+
<dt>Helps guide and speed up the development process</dt>
|
69
|
+
<dd>By focusing on getting the code to pass the tests, the programmer
|
70
|
+
can become more productive, not overspecify or get lost in premature
|
71
|
+
optimizations, and create code that is correct from the very beginning
|
72
|
+
(so-called <em>test-driven development</em>; see <a href="#Terminology">Terminology</a>).</dd>
|
73
|
+
<dt>Helps separate interface from implementation</dt>
|
74
|
+
<dd>When writing tests, the programmer may discover dependencies
|
75
|
+
(in order to get the tests to run) that ought not to be there, and
|
76
|
+
which need to be abstracted away to get a cleaner design. This helps
|
77
|
+
eliminate bad dependencies before they spread throughout the
|
78
|
+
code.</dd>
|
79
|
+
<dt>Makes component integration easier</dt>
|
80
|
+
<dd>By testing in a bottom-up fashion, beginning with the smallest
|
81
|
+
program units and creating a confidence in that they work as they
|
82
|
+
should, it becomes easier to test that a higher-level component,
|
83
|
+
consisting of several such units, also behaves according to
|
84
|
+
specification (known as <em>integration testing</em>; see <a href="#Terminology">Terminology</a>).</dd>
|
85
|
+
<dt>Is self-documenting</dt>
|
86
|
+
<dd>The tests can be read as documentation, typically showing both
|
87
|
+
examples of correct and incorrect usage, along with the expected
|
88
|
+
consequences.</dd>
|
89
|
+
</dl>
|
90
|
+
|
91
|
+
<h3><a name="Terminology">Terminology</a></h3>
|
92
|
+
|
93
|
+
<dl>
|
94
|
+
<dt>Unit testing</dt>
|
95
|
+
<dd>Testing that a program unit behaves as it is supposed to do (in
|
96
|
+
itself), according to its specifications. Unit tests have an important
|
97
|
+
function as regression tests, when the program later is modified for
|
98
|
+
some reason, since they check that the program still behaves according
|
99
|
+
to specification.</dd>
|
100
|
+
<dt>Regression testing</dt>
|
101
|
+
<dd>Running a set of tests after making changes to a program, to check
|
102
|
+
that the program behaves as it did before the changes (except, of
|
103
|
+
course, for any intentional changes in behaviour). Unit tests are
|
104
|
+
important as regression tests, but regression testing can involve more
|
105
|
+
than just unit testing, and may also test behaviour that might not be
|
106
|
+
part of the normal specification (such as bug-for-bug-compatibility).
|
107
|
+
</dd>
|
108
|
+
<dt>Integration testing</dt>
|
109
|
+
<dd>Testing that a number of individually developed program units
|
110
|
+
(assumed to already have been separately unit tested) work together as
|
111
|
+
expected. Depending on the system being developed, integration testing
|
112
|
+
may be as simple as "just another level of unit testing", but might
|
113
|
+
also involve other kinds of tests (compare <em>system testing</em>).
|
114
|
+
</dd>
|
115
|
+
<dt>System testing</dt>
|
116
|
+
<dd>Testing that a complete system behaves according to its
|
117
|
+
specification. Specifically, system testing should not require knowing
|
118
|
+
any details about the implementation. It typically involves testing
|
119
|
+
many different aspects of the system behaviour apart from the basic
|
120
|
+
functionality, such as performance, usability, and reliability.</dd>
|
121
|
+
<dt>Test-driven development</dt>
|
122
|
+
<dd>A program development technique where you continuously write tests
|
123
|
+
<em>before</em> you implement the code that is supposed to pass those
|
124
|
+
tests. This can help you focus on solving the right problems, and not
|
125
|
+
make a more complicated implementation than necessary, by letting the
|
126
|
+
unit tests determine when a program is "done": if it fulfils its
|
127
|
+
specifications, there is no need to keep adding functionality.</dd>
|
128
|
+
<dt>Mock object</dt>
|
129
|
+
<dd>Sometimes, testing some unit <code>A</code> (e.g., a function) requires that
|
130
|
+
it collaborates somehow with some other unit <code>B</code> (perhaps being passed
|
131
|
+
as an argument, or by reference) - but <code>B</code> has not been implemented
|
132
|
+
yet. A "mock object" - an object which, for the purposes of testing
|
133
|
+
<code>A</code>, looks and behaves like a real <code>B</code> - might then be used instead.
|
134
|
+
(This is of course only useful if it would be significantly more work
|
135
|
+
to implement a real <code>B</code> than to create a mock object.)</dd>
|
136
|
+
<dt>Test case</dt>
|
137
|
+
<dd>A single, well-defined test, that somehow can be uniquely
|
138
|
+
identified. When executed, the test case either <em>passes</em> or
|
139
|
+
<em>fails</em>; the test report should identify exactly which test
|
140
|
+
cases failed.</dd>
|
141
|
+
<dt>Test suite</dt>
|
142
|
+
<dd>A collection of test cases, generally with a specific, common
|
143
|
+
target for testing, such as a single function, module, or subsystem. A
|
144
|
+
test suite may also be recursively composed by smaller test
|
145
|
+
suites.</dd>
|
146
|
+
</dl>
|
147
|
+
|
148
|
+
<h3><a name="Getting_started">Getting started</a></h3>
|
149
|
+
<ul>
|
150
|
+
<li><a href="#Including_the_EUnit_header_file">Including the EUnit header file</a></li>
|
151
|
+
<li><a href="#Writing_simple_test_functions">Writing simple test functions</a></li>
|
152
|
+
<li><a href="#Running_EUnit">Running EUnit</a></li>
|
153
|
+
<li><a href="#Writing_test_generating_functions">Writing test generating functions</a></li>
|
154
|
+
<li><a href="#An_example">An example</a></li>
|
155
|
+
<li><a href="#Disabling_testing">Disabling testing</a></li>
|
156
|
+
<li><a href="#Avoiding_compile-time_dependency_on_EUnit">Avoiding compile-time dependency on EUnit</a></li>
|
157
|
+
</ul>
|
158
|
+
|
159
|
+
<h4><a name="Including_the_EUnit_header_file">Including the EUnit header file</a></h4>
|
160
|
+
|
161
|
+
The simplest way to use EUnit in an Erlang module is to add the
|
162
|
+
following line at the beginning of the module (after the <code>-module</code>
|
163
|
+
declaration, but before any function definitions):
|
164
|
+
<pre> -include_lib("eunit/include/eunit.hrl").</pre>
|
165
|
+
|
166
|
+
This will have the following effect:
|
167
|
+
<ul>
|
168
|
+
<li>Creates an exported function <code>test()</code> (unless testing is turned
|
169
|
+
off, and the module does not already contain a test() function), that
|
170
|
+
can be used to run all the unit tests defined in the module</li>
|
171
|
+
<li>Causes all functions whose names match <code>..._test()</code> or <code>..._test_()</code>
|
172
|
+
to be automatically exported from the module (unless testing is
|
173
|
+
turned off, or the <code>EUNIT_NOAUTO</code> macro is defined)</li>
|
174
|
+
<li>Makes all the preprocessor macros of EUnit available, to help
|
175
|
+
writing tests</li>
|
176
|
+
</ul>
|
177
|
+
|
178
|
+
<strong>Note:</strong> For <code>-include_lib(...)</code> to work, the Erlang
|
179
|
+
module search path <em>must</em> contain a directory whose name ends in
|
180
|
+
<code>eunit/ebin</code> (pointing to the <code>ebin</code> subdirectory of the EUnit
|
181
|
+
installation directory). If EUnit is installed as <code>lib/eunit</code> under your
|
182
|
+
Erlang/OTP system directory, its <code>ebin</code> subdirectory will be
|
183
|
+
automatically added to the search path when Erlang starts. Otherwise,
|
184
|
+
you need to add the directory explicitly, by passing a <code>-pa</code> flag to the
|
185
|
+
<code>erl</code> or <code>erlc</code> command. For example, a Makefile could contain the
|
186
|
+
following action for compiling <code>.erl</code> files:
|
187
|
+
<pre> erlc -pa "path/to/eunit/ebin" $(ERL_COMPILE_FLAGS) -o$(EBIN) $<</pre>
|
188
|
+
or if you want Eunit to always be available when you run Erlang
|
189
|
+
interactively, you can add a line like the following to your
|
190
|
+
<code>$HOME/.erlang</code> file:
|
191
|
+
<pre> code:add_path("/path/to/eunit/ebin").</pre>
|
192
|
+
|
193
|
+
<h4><a name="Writing_simple_test_functions">Writing simple test functions</a></h4>
|
194
|
+
|
195
|
+
<p>The EUnit framework makes it extremely easy to write unit tests in
|
196
|
+
Erlang. There are a few different ways of writing them, though, so we
|
197
|
+
start with the simplest:</p>
|
198
|
+
|
199
|
+
<p>A function with a name ending in <code>..._test()</code> is recognized by EUnit as
|
200
|
+
a simple test function - it takes no arguments, and its execution either
|
201
|
+
succeeds (returning some arbitrary value that EUnit will throw away), or
|
202
|
+
fails by throwing an exception of some kind (or by not terminating, in
|
203
|
+
which case it will be aborted after a while).</p>
|
204
|
+
|
205
|
+
An example of a simple test function could be the following:
|
206
|
+
<pre> reverse_test() -> lists:reverse([1,2,3]).</pre><p>
|
207
|
+
This just tests that the function <code>lists:reverse(List)</code> does not crash
|
208
|
+
when <code>List</code> is <code>[1,2,3]</code>. It is not a great test, but many people write
|
209
|
+
simple functions like this one to test the basic functionality of their
|
210
|
+
code, and those tests can be used directly by EUnit, without changes,
|
211
|
+
as long as their function names match.</p>
|
212
|
+
|
213
|
+
<h5><a name="Use_exceptions_to_signal_failure">Use exceptions to signal failure</a></h5>
|
214
|
+
|
215
|
+
To write more interesting tests, we need to make them crash (throw an
|
216
|
+
exception) when they don't get the result they expect. A simple way of
|
217
|
+
doing this is to use pattern matching with <code>=</code>, as in the following
|
218
|
+
examples:
|
219
|
+
<pre> reverse_nil_test() -> [] = lists:reverse([]).
|
220
|
+
reverse_one_test() -> [1] = lists:reverse([1]).
|
221
|
+
reverse_two_test() -> [2,1] = lists:reverse([1,2]).</pre><p>
|
222
|
+
If there was some bug in <code>lists:reverse/1</code> that made it return something
|
223
|
+
other than <code>[2,1]</code> when it got <code>[1,2]</code> as input, then the last test
|
224
|
+
above would throw a <code>badmatch</code> error. The first two (we assume they do
|
225
|
+
not get a <code>badmatch</code>) would simply return <code>[]</code> and <code>[1]</code>, respectively,
|
226
|
+
so both succeed. (Note that EUnit is not psychic: if you write a test
|
227
|
+
that returns a value, even if it is the wrong value, EUnit will consider
|
228
|
+
it a success. You must make sure that the test is written so that it
|
229
|
+
causes a crash if the result is not what it should be.)</p>
|
230
|
+
|
231
|
+
<h5><a name="Using_assert_macros">Using assert macros</a></h5>
|
232
|
+
|
233
|
+
If you want to use Boolean operators for your tests, the <code>assert</code>
|
234
|
+
macro comes in handy (see <a href="#EUnit_macros">EUnit macros</a> for details):
|
235
|
+
<pre> length_test() -> ?assert(length([1,2,3]) == 3).</pre><p>
|
236
|
+
The <code>?assert(Expression)</code> macro will evaluate <code>Expression</code>, and if that
|
237
|
+
does not evaluate to <code>true</code>, it will throw an exception; otherwise it
|
238
|
+
just returns <code>ok</code>. In the above example, the test will thus fail if the
|
239
|
+
call to <code>length</code> does not return 3.</p>
|
240
|
+
|
241
|
+
<h4><a name="Running_EUnit">Running EUnit</a></h4>
|
242
|
+
|
243
|
+
<p>If you have added the declaration
|
244
|
+
<code>-include_lib("eunit/include/eunit.hrl")</code> to your module, as described
|
245
|
+
above, you only need to compile the module, and run the automatically
|
246
|
+
exported function <code>test()</code>. For example, if your module was named <code>m</code>,
|
247
|
+
then calling <code>m:test()</code> will run EUnit on all the tests defined in the
|
248
|
+
module. You do not need to write <code>-export</code> declarations for the test
|
249
|
+
functions. This is all done by magic.</p>
|
250
|
+
|
251
|
+
<h5><a name="EUnit_captures_standard_output">EUnit captures standard output</a></h5>
|
252
|
+
|
253
|
+
<p>If your test code writes to the standard output, you may be surprised to
|
254
|
+
see that the text does not appear on the console when the tests are
|
255
|
+
running. This is because EUnit captures all standard output from test
|
256
|
+
functions (this also includes setup and cleanup functions, but not
|
257
|
+
generator functions), so that it can be included in the test report if
|
258
|
+
errors occur. To bypass EUnit and print text directly to the console
|
259
|
+
while testing, you can write to the 'user' output stream, as in
|
260
|
+
<code>io:format(user, "~w", [Term])</code>. The recommended way of doing this is to
|
261
|
+
use the EUnit <a href="#Debugging_Macros">Debugging Macros</a>, which make it much simpler.</p>
|
262
|
+
|
263
|
+
<h4><a name="Writing_test_generating_functions">Writing test generating functions</a></h4>
|
264
|
+
|
265
|
+
<p>A drawback of simple test functions is that you must write a separate
|
266
|
+
function (with a separate name) for each test case. A more compact way
|
267
|
+
of writing tests (and much more flexible, as we shall see), is to write
|
268
|
+
functions that <em>return</em> tests, instead of <em>being</em> tests.</p>
|
269
|
+
|
270
|
+
<p>A function with a name ending in <code>..._test_()</code> (note the final
|
271
|
+
underscore) is recognized by EUnit as a <em>test generator</em>
|
272
|
+
function. Test generators return a <em>representation</em> of a <em>set
|
273
|
+
of tests</em> to be executed by EUnit.</p>
|
274
|
+
|
275
|
+
<h5><a name="Representing_a_test_as_data">Representing a test as data</a></h5>
|
276
|
+
|
277
|
+
The most basic representation of a test is a single fun-expression that
|
278
|
+
takes no arguments. For example, the following test generator:
|
279
|
+
<pre> basic_test_() ->
|
280
|
+
fun () -> ?assert(1 + 1 == 2) end.</pre>
|
281
|
+
will have the same effect as the following simple test:
|
282
|
+
<pre> simple_test() ->
|
283
|
+
?assert(1 + 1 == 2).</pre><p>
|
284
|
+
(in fact, EUnit will handle all simple tests just like it handles
|
285
|
+
fun-expressions: it will put them in a list, and run them one by one).</p>
|
286
|
+
|
287
|
+
<h5><a name="Using_macros_to_write_tests">Using macros to write tests</a></h5>
|
288
|
+
|
289
|
+
To make tests more compact and readable, as well as automatically add
|
290
|
+
information about the line number in the source code where a test
|
291
|
+
occurred (and reduce the number of characters you have to type), you can
|
292
|
+
use the <code>_test</code> macro (note the initial underscore character), like
|
293
|
+
this:
|
294
|
+
<pre> basic_test_() ->
|
295
|
+
?_test(?assert(1 + 1 == 2)).</pre><p>
|
296
|
+
The <code>_test</code> macro takes any expression (the "body") as argument, and
|
297
|
+
places it within a fun-expression (along with some extra information).
|
298
|
+
The body can be any kind of test expression, just like the body of a
|
299
|
+
simple test function.</p>
|
300
|
+
|
301
|
+
<h5><a name="Underscore-prefixed_macros_create_test_objects">Underscore-prefixed macros create test objects</a></h5>
|
302
|
+
|
303
|
+
But this example can be made even shorter! Most test macros, such as the
|
304
|
+
family of <code>assert</code> macros, have a corresponding form with an initial
|
305
|
+
underscore character, which automatically adds a <code>?_test(...)</code> wrapper.
|
306
|
+
The above example can then simply be written:
|
307
|
+
<pre> basic_test_() ->
|
308
|
+
?_assert(1 + 1 == 2).</pre><p>
|
309
|
+
which has exactly the same meaning (note the <code>_assert</code> instead of
|
310
|
+
<code>assert</code>). You can think of the initial underscore as signalling
|
311
|
+
<em>test object</em>.</p>
|
312
|
+
|
313
|
+
<h4><a name="An_example">An example</a></h4>
|
314
|
+
|
315
|
+
Sometimes, an example says more than a thousand words. The following
|
316
|
+
small Erlang module shows how EUnit can be used in practice.
|
317
|
+
<pre> -module(fib).
|
318
|
+
-export([fib/1]).
|
319
|
+
-include_lib("eunit/include/eunit.hrl").
|
320
|
+
|
321
|
+
fib(0) -> 1;
|
322
|
+
fib(1) -> 1;
|
323
|
+
fib(N) when N > 1 -> fib(N-1) + fib(N-2).
|
324
|
+
|
325
|
+
fib_test_() ->
|
326
|
+
[?_assert(fib(0) == 1),
|
327
|
+
?_assert(fib(1) == 1),
|
328
|
+
?_assert(fib(2) == 2),
|
329
|
+
?_assert(fib(3) == 3),
|
330
|
+
?_assert(fib(4) == 5),
|
331
|
+
?_assert(fib(5) == 8),
|
332
|
+
?_assertException(error, function_clause, fib(-1)),
|
333
|
+
?_assert(fib(31) == 2178309)
|
334
|
+
].</pre>
|
335
|
+
|
336
|
+
<p>(Author's note: When I first wrote this example, I happened to write a
|
337
|
+
<code>*</code> instead of <code>+</code> in the <code>fib</code> function. Of course, this showed up
|
338
|
+
immediately when I ran the tests.)</p>
|
339
|
+
|
340
|
+
<p>See <a href="#EUnit_test_representation">EUnit test representation</a> for a full list of all the ways
|
341
|
+
you can specify test sets in EUnit.</p>
|
342
|
+
|
343
|
+
<h4><a name="Disabling_testing">Disabling testing</a></h4>
|
344
|
+
|
345
|
+
Testing can be turned off by defining the <code>NOTEST</code> macro when compiling,
|
346
|
+
for example as an option to <code>erlc</code>, as in:
|
347
|
+
<pre> erlc -DNOTEST my_module.erl</pre>
|
348
|
+
or by adding a macro definition to the code, <em>before the EUnit header
|
349
|
+
file is included</em>:
|
350
|
+
<pre> -define(NOTEST, 1).</pre><p>
|
351
|
+
(the value is not important, but should typically be 1 or <code>true</code>).
|
352
|
+
Note that unless the <code>EUNIT_NOAUTO</code> macro is defined, disabling testing
|
353
|
+
will also automatically strip all test functions from the code, except
|
354
|
+
for any that are explicitly declared as exported.</p>
|
355
|
+
|
356
|
+
For instance, to use EUnit in your application, but with testing turned
|
357
|
+
off by default, put the following lines in a header file:
|
358
|
+
<pre> -define(NOTEST, true).
|
359
|
+
-include_lib("eunit/include/eunit.hrl").</pre>
|
360
|
+
and then make sure that every module of your application includes that
|
361
|
+
header file. This means that you have a only a single place to modify in
|
362
|
+
order to change the default setting for testing. To override the <code>NOTEST</code>
|
363
|
+
setting without modifying the code, you can define <code>TEST</code> in a compiler
|
364
|
+
option, like this:
|
365
|
+
<pre> erlc -DTEST my_module.erl</pre>
|
366
|
+
|
367
|
+
<p>See <a href="#Compilation_control_macros">Compilation control macros</a> for details about these
|
368
|
+
macros.</p>
|
369
|
+
|
370
|
+
<h4><a name="Avoiding_compile-time_dependency_on_EUnit">Avoiding compile-time dependency on EUnit</a></h4>
|
371
|
+
|
372
|
+
If you are distributing the source code for your application for other
|
373
|
+
people to compile and run, you probably want to ensure that the code
|
374
|
+
compiles even if EUnit is not available. Like the example in the
|
375
|
+
previous section, you can put the following lines in a common header
|
376
|
+
file:
|
377
|
+
<pre> -ifdef(TEST).
|
378
|
+
-include_lib("eunit/include/eunit.hrl").
|
379
|
+
-endif.</pre><p>
|
380
|
+
and, of course, also make sure that you place all test code that uses
|
381
|
+
EUnit macros within <code>-ifdef(TEST)</code> or <code>-ifdef(EUNIT)</code> sections.</p>
|
382
|
+
|
383
|
+
|
384
|
+
<h3><a name="EUnit_macros">EUnit macros</a></h3>
|
385
|
+
|
386
|
+
<p>Although all the functionality of EUnit is avaliable even without the
|
387
|
+
use of preprocessor macros, the EUnit header file defines a number of
|
388
|
+
such macros in order to make it as easy as possible to write unit tests
|
389
|
+
as compactly as possible and without getting too many details in the
|
390
|
+
way.</p>
|
391
|
+
|
392
|
+
<p>Except where explicitly stated, using EUnit macros will never introduce
|
393
|
+
run-time dependencies on the EUnit library code, regardless of whether
|
394
|
+
your code is compiled with testing enabled or disabled.</p>
|
395
|
+
|
396
|
+
<ul>
|
397
|
+
<li><a href="#Basic_macros">Basic macros</a></li>
|
398
|
+
<li><a href="#Compilation_control_macros">Compilation control macros</a></li>
|
399
|
+
<li><a href="#Utility_macros">Utility macros</a></li>
|
400
|
+
<li><a href="#Assert_macros">Assert macros</a></li>
|
401
|
+
<li><a href="#Macros_for_running_external_commands">Macros for running external commands</a></li>
|
402
|
+
<li><a href="#Debugging_Macros">Debugging Macros</a></li>
|
403
|
+
</ul>
|
404
|
+
|
405
|
+
<h4><a name="Basic_macros">Basic macros</a></h4>
|
406
|
+
|
407
|
+
<dl>
|
408
|
+
<dt><code>_test(Expr)</code></dt>
|
409
|
+
<dd>Turns <code>Expr</code> into a "test object", by wrapping it in a
|
410
|
+
fun-expression and a source line number. Technically, this is the same
|
411
|
+
as <code>{?LINE, fun () -> (Expr) end}</code>.
|
412
|
+
</dd>
|
413
|
+
</dl>
|
414
|
+
|
415
|
+
<h4><a name="Compilation_control_macros">Compilation control macros</a></h4>
|
416
|
+
|
417
|
+
<dl>
|
418
|
+
<dt><code>EUNIT</code></dt>
|
419
|
+
<dd>This macro is always defined to <code>true</code> whenever EUnit is enabled at
|
420
|
+
compile time. This is typically used to place testing code within
|
421
|
+
conditional compilation, as in:
|
422
|
+
<pre> -ifdef(EUNIT).
|
423
|
+
% test code here
|
424
|
+
...
|
425
|
+
-endif.</pre>
|
426
|
+
e.g., to ensure that the code can be compiled without including the
|
427
|
+
EUnit header file, when testing is disabled. See also the macros <code>TEST</code>
|
428
|
+
and <code>NOTEST</code>.
|
429
|
+
</dd>
|
430
|
+
<dt><code>TEST</code></dt>
|
431
|
+
<dd><p>This macro is always defined (to <code>true</code>, unless previously defined
|
432
|
+
by the user to have another value) whenever EUnit is enabled at compile
|
433
|
+
time. This can be used to place testing code within conditional
|
434
|
+
compilation; see also the macros <code>NOTEST</code> and <code>EUNIT</code>.</p>
|
435
|
+
|
436
|
+
<p>For testing code that is strictly dependent on EUnit, it may be
|
437
|
+
preferable to use the <code>EUNIT</code> macro for this purpose, while for code
|
438
|
+
that uses more generic testing conventions, using the <code>TEST</code> macro may
|
439
|
+
be preferred.</p>
|
440
|
+
|
441
|
+
The <code>TEST</code> macro can also be used to override the <code>NOTEST</code> macro. If
|
442
|
+
<code>TEST</code> is defined <em>before</em> the EUnit header file is
|
443
|
+
included (even if <code>NOTEST</code> is also defined), then the code will be
|
444
|
+
compiled with EUnit enabled.
|
445
|
+
</dd>
|
446
|
+
<dt><code>NOTEST</code></dt>
|
447
|
+
<dd><p>This macro is always defined (to <code>true</code>, unless previously defined
|
448
|
+
by the user to have another value) whenever EUnit is <em>disabled</em>
|
449
|
+
at compile time. (Compare the <code>TEST</code> macro.)</p>
|
450
|
+
|
451
|
+
This macro can also be used for conditional compilation, but is more
|
452
|
+
typically used to disable testing: If <code>NOTEST</code> is defined
|
453
|
+
<em>before</em> the EUnit header file is included, and <code>TEST</code>
|
454
|
+
is <em>not</em> defined, then the code will be compiled with EUnit
|
455
|
+
disabled. See also <a href="#Disabling_testing">Disabling testing</a>.
|
456
|
+
</dd>
|
457
|
+
|
458
|
+
<dt><code>EUNIT_NOAUTO</code></dt>
|
459
|
+
<dd>If this macro is defined, the automatic exporting or stripping of
|
460
|
+
test functions will be disabled.
|
461
|
+
</dd>
|
462
|
+
</dl>
|
463
|
+
|
464
|
+
<h4><a name="Utility_macros">Utility macros</a></h4>
|
465
|
+
|
466
|
+
<p>The following macros can make tests more compact and readable:</p>
|
467
|
+
|
468
|
+
<dl>
|
469
|
+
<dt><code>LET(Var,Arg,Expr)</code></dt>
|
470
|
+
<dd>Creates a local binding <code>Var = Arg</code> in <code>Expr</code>. (This is the same as
|
471
|
+
<code>(fun(Var)->(Expr)end)(Arg)</code>.) Note that the binding is not exported
|
472
|
+
outside of <code>Expr</code>, and that within <code>Expr</code>, this binding of <code>Var</code> will
|
473
|
+
shadow any binding of <code>Var</code> in the surrounding scope.
|
474
|
+
</dd>
|
475
|
+
<dt><code>IF(Cond,TrueCase,FalseCase)</code></dt>
|
476
|
+
<dd>Evaluates <code>TrueCase</code> if <code>Cond</code> evaluates to <code>true</code>, or otherwise
|
477
|
+
evaluates <code>FalseCase</code> if <code>Cond</code> evaluates to <code>false</code>. (This is the same
|
478
|
+
as <code>(case (Cond) of true->(TrueCase); false->(FalseCase) end)</code>.) Note
|
479
|
+
that it is an error if <code>Cond</code> does not yield a boolean value.
|
480
|
+
</dd>
|
481
|
+
</dl>
|
482
|
+
|
483
|
+
<h4><a name="Assert_macros">Assert macros</a></h4>
|
484
|
+
|
485
|
+
<p>(Note that these macros also have corresponding forms which start with
|
486
|
+
an "<code>_</code>" (underscore) character, as in <code>?_assert(BoolExpr)</code>, that create
|
487
|
+
a "test object" instead of performing the test immediately. This is
|
488
|
+
equivalent to writing <code>?_test(assert(BoolExpr))</code>, etc.)</p>
|
489
|
+
|
490
|
+
<dl>
|
491
|
+
<dt><code>assert(BoolExpr)</code></dt>
|
492
|
+
<dd><p>Evaluates the expression <code>BoolExpr</code>, if testing is enabled. Unless
|
493
|
+
the result is <code>true</code>, an informative exception will be generated. If
|
494
|
+
there is no exception, the result of the macro expression is the atom
|
495
|
+
<code>ok</code>, and the value of <code>BoolExpr</code> is discarded. If testing is disabled,
|
496
|
+
the macro will not generate any code except the atom <code>ok</code>, and
|
497
|
+
<code>BoolExpr</code> will not be evaluated.</p>
|
498
|
+
|
499
|
+
Typical usage:
|
500
|
+
<pre> ?assert(f(X, Y) == [])</pre>
|
501
|
+
|
502
|
+
The <code>assert</code> macro can be used anywhere in a program, not just in unit
|
503
|
+
tests, to check pre/postconditions and invariants. For example:
|
504
|
+
<pre> some_recursive_function(X, Y, Z) ->
|
505
|
+
?assert(X + Y > Z),
|
506
|
+
...</pre>
|
507
|
+
</dd>
|
508
|
+
<dt><code>assertNot(BoolExpr)</code></dt>
|
509
|
+
<dd>Equivalent to <code>assert(not (BoolExpr))</code>.
|
510
|
+
</dd>
|
511
|
+
<dt><code>assertMatch(GuardedPattern, Expr)</code></dt>
|
512
|
+
<dd><p>Evaluates <code>Expr</code> and matches the result against <code>GuardedPattern</code>, if
|
513
|
+
testing is enabled. If the match fails, an informative exception will be
|
514
|
+
generated; see the <code>assert</code> macro for further details. <code>GuardedPattern</code>
|
515
|
+
can be anything that you can write on the left hand side of the <code>-></code>
|
516
|
+
symbol in a case-clause, except that it cannot contain comma-separated
|
517
|
+
guard tests.</p>
|
518
|
+
|
519
|
+
<p>The main reason for using <code>assertMatch</code> also for simple matches, instead
|
520
|
+
of matching with <code>=</code>, is that it produces more detailed error messages.</p>
|
521
|
+
|
522
|
+
Examples:
|
523
|
+
<pre> ?assertMatch({found, {fred, _}}, lookup(bloggs, Table))</pre>
|
524
|
+
<pre> ?assertMatch([X|_] when X > 0, binary_to_list(B))</pre>
|
525
|
+
</dd>
|
526
|
+
<dt><code>assertEqual(Expect, Expr)</code></dt>
|
527
|
+
<dd><p>Evaluates the expressions <code>Expect</code> and <code>Expr</code> and compares the
|
528
|
+
results for equality, if testing is enabled. If the values are not
|
529
|
+
equal, an informative exception will be generated; see the <code>assert</code>
|
530
|
+
macro for further details.</p>
|
531
|
+
|
532
|
+
<p><code>assertEqual</code> is more suitable than than <code>assertMatch</code> when the
|
533
|
+
left-hand side is a computed value rather than a simple pattern, and
|
534
|
+
gives more details than <code>?assert(Expect =:= Expr)</code>.</p>
|
535
|
+
|
536
|
+
Examples:
|
537
|
+
<pre> ?assertEqual("b" ++ "a", lists:reverse("ab"))</pre>
|
538
|
+
<pre> ?assertEqual(foo(X), bar(Y))</pre>
|
539
|
+
</dd>
|
540
|
+
<dt><code>assertException(ClassPattern, TermPattern, Expr)</code></dt>
|
541
|
+
<dt><code>assertError(TermPattern, Expr)</code></dt>
|
542
|
+
<dt><code>assertExit(TermPattern, Expr)</code></dt>
|
543
|
+
<dt><code>assertThrow(TermPattern, Expr)</code></dt>
|
544
|
+
<dd><p>Evaluates <code>Expr</code>, catching any exception and testing that it matches
|
545
|
+
the expected <code>ClassPattern:TermPattern</code>. If the match fails, or if no
|
546
|
+
exception is thrown by <code>Expr</code>, an informative exception will be
|
547
|
+
generated; see the <code>assert</code> macro for further details. The
|
548
|
+
<code>assertError</code>, <code>assertExit</code>, and <code>assertThrow</code> macros, are equivalent to
|
549
|
+
using <code>assertException</code> with a <code>ClassPattern</code> of <code>error</code>, <code>exit</code>, or
|
550
|
+
<code>throw</code>, respectively.</p>
|
551
|
+
|
552
|
+
Examples:
|
553
|
+
<pre> ?assertError(badarith, X/0)</pre>
|
554
|
+
<pre> ?assertExit(normal, exit(normal))</pre>
|
555
|
+
<pre> ?assertException(throw, {not_found,_}, throw({not_found,42}))</pre>
|
556
|
+
</dd>
|
557
|
+
</dl>
|
558
|
+
|
559
|
+
<h4><a name="Macros_for_running_external_commands">Macros for running external commands</a></h4>
|
560
|
+
|
561
|
+
<p>Keep in mind that external commands are highly dependent on the
|
562
|
+
operating system. You can use the standard library function <code>os:type()</code>
|
563
|
+
in test generator functions, to produce different sets of tests
|
564
|
+
depending on the current operating system.</p>
|
565
|
+
|
566
|
+
<p>Note: these macros introduce a run-time dependency on the EUnit library
|
567
|
+
code, if compiled with testing enabled.</p>
|
568
|
+
|
569
|
+
<dl>
|
570
|
+
<dt><code>assertCmd(CommandString)</code></dt>
|
571
|
+
<dd><p>Runs <code>CommandString</code> as an external command, if testing is enabled.
|
572
|
+
Unless the returned status value is 0, an informative exception will be
|
573
|
+
generated. If there is no exception, the result of the macro expression
|
574
|
+
is the atom <code>ok</code>. If testing is disabled, the macro will not generate
|
575
|
+
any code except the atom <code>ok</code>, and the command will not be executed.</p>
|
576
|
+
|
577
|
+
Typical usage:
|
578
|
+
<pre> ?assertCmd("mkdir foo")</pre>
|
579
|
+
</dd>
|
580
|
+
<dt><code>assertCmdStatus(N, CommandString)</code></dt>
|
581
|
+
<dd>Like the <code>assertCmd(CommandString)</code> macro, but generates an
|
582
|
+
exception unless the returned status value is <code>N</code>.
|
583
|
+
</dd>
|
584
|
+
<dt><code>assertCmdOutput(Text, CommandString)</code></dt>
|
585
|
+
<dd>Runs <code>CommandString</code> as an external command, if testing is enabled.
|
586
|
+
Unless the output produced by the command exactly matches the specified
|
587
|
+
string <code>Text</code>, an informative exception will be generated. (Note that
|
588
|
+
the output is normalized to use a single LF character as line break on
|
589
|
+
all platforms.) If there is no exception, the result of the macro
|
590
|
+
expression is the atom <code>ok</code>. If testing is disabled, the macro will not
|
591
|
+
generate any code except the atom <code>ok</code>, and the command will not be
|
592
|
+
executed.
|
593
|
+
</dd>
|
594
|
+
<dt><code>cmd(CommandString)</code></dt>
|
595
|
+
<dd><p>Runs <code>CommandString</code> as an external command. Unless the returned
|
596
|
+
status value is 0 (indicating success), an informative exception will be
|
597
|
+
generated; otherwise, the result of the macro expression is the output
|
598
|
+
produced by the command, as a flat string. The output is normalized to
|
599
|
+
use a single LF character as line break on all platforms.</p>
|
600
|
+
|
601
|
+
<p>This macro is useful in the setup and cleanup sections of fixtures,
|
602
|
+
e.g., for creating and deleting files or perform similar operating
|
603
|
+
system specific tasks, to make sure that the test system is informed of
|
604
|
+
any failures.</p>
|
605
|
+
|
606
|
+
A Unix-specific example:
|
607
|
+
<pre> {setup,
|
608
|
+
fun () -> ?cmd("mktemp") end,
|
609
|
+
fun (FileName) -> ?cmd("rm " ++ FileName) end,
|
610
|
+
...}</pre>
|
611
|
+
</dd>
|
612
|
+
</dl>
|
613
|
+
|
614
|
+
<h4><a name="Debugging_Macros">Debugging Macros</a></h4>
|
615
|
+
|
616
|
+
<p>To help with debugging, EUnit defines several useful macros for printing
|
617
|
+
messages directly to the console (rather than to the standard output).
|
618
|
+
Furthermore, these macros all use the same basic format, which includes
|
619
|
+
the file and line number where they occur, making it possible in some
|
620
|
+
development environments (e.g., when running Erlang in an Emacs buffer)
|
621
|
+
to simply click on the message and jump directly to the corresponding
|
622
|
+
line in the code.</p>
|
623
|
+
|
624
|
+
<p>If the macro <code>NODEBUG</code> is defined before the EUnit header file is
|
625
|
+
included, these macros have no effect.</p>
|
626
|
+
|
627
|
+
<dl>
|
628
|
+
<dt><code>debugHere</code></dt>
|
629
|
+
<dd>Just prints a marker showing the current file and line number. Note
|
630
|
+
that this is an argument-less macro. The result is always <code>ok</code>.</dd>
|
631
|
+
<dt><code>debugMsg(Text)</code></dt>
|
632
|
+
<dd>Outputs the message <code>Text</code> (which can be a plain string, an IO-list,
|
633
|
+
or just an atom). The result is always <code>ok</code>.</dd>
|
634
|
+
<dt><code>debugFmt(FmtString, Args)</code></dt>
|
635
|
+
<dd>This formats the text like <code>io:format(FmtString, Args)</code> and outputs
|
636
|
+
it like <code>debugMsg</code>. The result is always <code>ok</code>.</dd>
|
637
|
+
<dt><code>debugVal(Expr)</code></dt>
|
638
|
+
<dd>Prints both the source code for <code>Expr</code> and its current value. E.g.,
|
639
|
+
<code>?debugVal(f(X))</code> might be displayed as "<code>f(X) = 42</code>". (Large terms are
|
640
|
+
shown truncated.) The result is always the value of <code>Expr</code>, so this
|
641
|
+
macro can be wrapped around any expression to display its value when
|
642
|
+
the code is compiled with debugging enabled.</dd>
|
643
|
+
<dt><code>debugTime(Text,Expr)</code></dt>
|
644
|
+
<dd>Prints <code>Text</code> and the wall clock time for evaluation of <code>Expr</code>. The
|
645
|
+
result is always the value of <code>Expr</code>, so this macro can be wrapped
|
646
|
+
around any expression to show its run time when the code is compiled
|
647
|
+
with debugging enabled. For example, <code>List1 = ?debugTime("sorting",
|
648
|
+
lists:sort(List))</code> might show as "<code>sorting: 0.015 s</code>".</dd>
|
649
|
+
|
650
|
+
</dl>
|
651
|
+
|
652
|
+
|
653
|
+
<h3><a name="EUnit_test_representation">EUnit test representation</a></h3>
|
654
|
+
|
655
|
+
<p>The way EUnit represents tests and test sets as data is flexible,
|
656
|
+
powerful, and concise. This section describes the representation in
|
657
|
+
detail.</p>
|
658
|
+
|
659
|
+
<ul>
|
660
|
+
<li><a href="#Simple_test_objects">Simple test objects</a></li>
|
661
|
+
<li><a href="#Test_sets_and_deep_lists">Test sets and deep lists</a></li>
|
662
|
+
<li><a href="#Titles">Titles</a></li>
|
663
|
+
<li><a href="#Primitives">Primitives</a></li>
|
664
|
+
<li><a href="#Control">Control</a></li>
|
665
|
+
<li><a href="#Fixtures">Fixtures</a></li>
|
666
|
+
<li><a href="#Lazy_generators">Lazy generators</a></li>
|
667
|
+
</ul>
|
668
|
+
|
669
|
+
<h4><a name="Simple_test_objects">Simple test objects</a></h4>
|
670
|
+
|
671
|
+
A <em>simple test object</em> is one of the following:
|
672
|
+
<ul>
|
673
|
+
<li>A nullary functional value (i.e., a fun that takes zero
|
674
|
+
arguments). Examples:
|
675
|
+
<pre> fun () -> ... end</pre>
|
676
|
+
<pre> fun some_function/0</pre>
|
677
|
+
<pre> fun some_module:some_function/0</pre>
|
678
|
+
</li>
|
679
|
+
<li>A pair of atoms <code>{ModuleName, FunctionName}</code>, referring to the
|
680
|
+
function <code>ModuleName:FunctionName/0</code></li>
|
681
|
+
<li>A pair <code>{LineNumber, SimpleTest}</code>, where <code>LineNumber</code> is a
|
682
|
+
nonnegative integer and <code>SimpleTest</code> is another simple test
|
683
|
+
object. <code>LineNumber</code> should indicate the source line of the test.
|
684
|
+
Pairs like this are usually only created via <code>?_test(...)</code> macros;
|
685
|
+
see <a href="#Basic_macros">Basic macros</a>.</li>
|
686
|
+
</ul><p>
|
687
|
+
In brief, a simple test object consists of a single function that takes
|
688
|
+
no arguments (possibly annotated with some additional metadata, i.e., a
|
689
|
+
line number). Evaluation of the function either <em>succeeds</em>, by
|
690
|
+
returning some value (which is ignored), or <em>fails</em>, by throwing
|
691
|
+
an exception.</p>
|
692
|
+
|
693
|
+
<h4><a name="Test_sets_and_deep_lists">Test sets and deep lists</a></h4>
|
694
|
+
|
695
|
+
<p>A test set can be easily created by placing a sequence of test objects
|
696
|
+
in a list. If <code>T_1</code>, ..., <code>T_N</code> are individual test objects, then <code>[T_1,
|
697
|
+
..., T_N]</code> is a test set consisting of those objects (in that order).</p>
|
698
|
+
|
699
|
+
<p>Test sets can be joined in the same way: if <code>S_1</code>, ..., <code>S_K</code> are test
|
700
|
+
sets, then <code>[S_1, ..., S_K]</code> is also a test set, where the tests of
|
701
|
+
<code>S_i</code> are ordered before those of <code>S_(i+1)</code>, for each subset <code>S_i</code>.</p>
|
702
|
+
|
703
|
+
<p>Thus, the main representation of test sets is <em>deep lists</em>, and
|
704
|
+
a simple test object can be viewed as a test set containing only a
|
705
|
+
single test; there is no difference between <code>T</code> and <code>[T]</code>.</p>
|
706
|
+
|
707
|
+
|
708
|
+
<h4><a name="Titles">Titles</a></h4>
|
709
|
+
|
710
|
+
<p>Any test or test set <code>T</code> can be annotated with a title, by wrapping it
|
711
|
+
in a pair <code>{Title, T}</code>, where <code>Title</code> is a string. For convenience, any
|
712
|
+
test which is normally represented using a tuple can simply be given a
|
713
|
+
title string as the first element, i.e., writing <code>{"The Title", ...}</code>
|
714
|
+
instead of adding an extra tuple wrapper as in <code>{"The Title", {...}}</code>.</p>
|
715
|
+
|
716
|
+
|
717
|
+
<h4><a name="Primitives">Primitives</a></h4>
|
718
|
+
|
719
|
+
The following are primitives, which do not contain other test sets as
|
720
|
+
arguments:
|
721
|
+
<dl>
|
722
|
+
<dt><code>{generator, GenFun::(() -> Tests)}</code>
|
723
|
+
</dt>
|
724
|
+
<dd>The generator function <code>GenFun</code> is called to produce a test
|
725
|
+
set.
|
726
|
+
</dd>
|
727
|
+
<dt><code>{generator, ModuleName::atom(), FunctionName::atom()}</code>
|
728
|
+
</dt>
|
729
|
+
<dd>The function <code>ModuleName:FunctionName()</code> is called to produce a test
|
730
|
+
set.
|
731
|
+
</dd>
|
732
|
+
<dt><code>ModuleName::atom()</code>
|
733
|
+
</dt>
|
734
|
+
<dd>A single atom represents a module name, and is equivalent to
|
735
|
+
<code>{module, ModuleName}</code>. This is often used as in the call
|
736
|
+
<code>eunit:test(some_module)</code>.
|
737
|
+
</dd>
|
738
|
+
<dt><code>{module, ModuleName::atom()}</code>
|
739
|
+
</dt>
|
740
|
+
<dd><p>This composes a test set from the exported test functions of the
|
741
|
+
named module, i.e., those functions with arity zero whose names end
|
742
|
+
with <code>_test</code> or <code>_test_</code>. Basically, the <code>..._test()</code> functions become
|
743
|
+
simple tests, while the <code>..._test_()</code> functions become generators.</p>
|
744
|
+
|
745
|
+
In addition, EUnit will also look for another module whose name is
|
746
|
+
<code>ModuleName</code> plus the suffix <code>_tests</code>, and if it exists, all the tests
|
747
|
+
from that module will also be added. (If <code>ModuleName</code> already contains
|
748
|
+
the suffix <code>_tests</code>, this is not done.) E.g., the specification
|
749
|
+
<code>{module, mymodule}</code> will run all tests in the modules <code>mymodule</code> and
|
750
|
+
<code>mymodule_tests</code>. Typically, the <code>_tests</code> module should only contain
|
751
|
+
test cases that use the public interface of the main module (and no
|
752
|
+
other code).
|
753
|
+
</dd>
|
754
|
+
<dt><code>{application, AppName::atom(), Info::list()}</code>
|
755
|
+
</dt>
|
756
|
+
<dd>This is a normal Erlang/OTP application descriptor, as found in an
|
757
|
+
<code>.app</code> file. The resulting test set consists of the modules listed in
|
758
|
+
the <code>modules</code> entry in <code>Info</code>.
|
759
|
+
</dd>
|
760
|
+
<dt><code>{application, AppName::atom()}</code>
|
761
|
+
</dt>
|
762
|
+
<dd>This creates a test set from all the modules belonging to the
|
763
|
+
specified application, by consulting the application's <code>.app</code> file
|
764
|
+
(see <code>{file, FileName}</code>), or if no such file exists, by testing all
|
765
|
+
object files in the application's <tt>ebin</tt>-directory (see <code>{dir,
|
766
|
+
Path}</code>); if that does not exist, the <code>code:lib_dir(AppName)</code> directory
|
767
|
+
is used.
|
768
|
+
</dd>
|
769
|
+
<dt><code>Path::string()</code>
|
770
|
+
</dt>
|
771
|
+
<dd>A single string represents the path of a file or directory, and is
|
772
|
+
equivalent to <code>{file, Path}</code>, or <code>{dir, Path}</code>, respectively, depending
|
773
|
+
on what <code>Path</code> refers to in the file system.
|
774
|
+
</dd>
|
775
|
+
<dt><code>{file, FileName::string()}</code>
|
776
|
+
</dt>
|
777
|
+
<dd><p>If <code>FileName</code> has a suffix that indicates an object file (<code>.beam</code>),
|
778
|
+
EUnit will try to reload the module from the specified file and test it.
|
779
|
+
Otherwise, the file is assumed to be a text file containing test
|
780
|
+
specifications, which will be read using the standard library function
|
781
|
+
<code>file:path_consult/2</code>.</p>
|
782
|
+
|
783
|
+
Unless the file name is absolute, the file is first searched for
|
784
|
+
relative to the current directory, and then using the normal search path
|
785
|
+
(<code>code:get_path()</code>). This means that the names of typical "app" files
|
786
|
+
can be used directly, without a path, e.g., <code>"mnesia.app"</code>.
|
787
|
+
</dd>
|
788
|
+
<dt><code>{dir, Path::string()}</code>
|
789
|
+
</dt>
|
790
|
+
<dd>This tests all object files in the specified directory, as if they
|
791
|
+
had been individually specified using <code>{file, FileName}</code>.
|
792
|
+
</dd>
|
793
|
+
<dt><code>{with, X::any(), [AbstractTestFun::((any()) -> any())]}</code>
|
794
|
+
</dt>
|
795
|
+
<dd>Distributes the value <code>X</code> over the unary functions in the list,
|
796
|
+
turning them into nullary test functions. An <code>AbstractTestFun</code> is like
|
797
|
+
an ordinary test fun, but takes one argument instead of zero - it's
|
798
|
+
basically missing some information before it can be a proper test. In
|
799
|
+
practice, <code>{with, X, [F_1, ..., F_N]}</code> is equivalent to <code>[fun () ->
|
800
|
+
F_1(X) end, ..., fun () -> F_N(X) end]</code>. This is particularly useful if
|
801
|
+
your abstract test functions are already implemented as proper
|
802
|
+
functions: <code>{with, FD, [fun filetest_a/1, fun filetest_b/1, fun
|
803
|
+
filetest_c/1]}</code> is equivalent to <code>[fun () -> filetest_a(FD) end, fun ()
|
804
|
+
-> filetest_b(FD) end, fun () -> filetest_c(FD) end]</code>, but much more
|
805
|
+
compact. See also <a href="#Fixtures">Fixtures</a>, below.
|
806
|
+
</dd>
|
807
|
+
</dl>
|
808
|
+
|
809
|
+
<h4><a name="Control">Control</a></h4>
|
810
|
+
|
811
|
+
The following representations control how and where tests are executed:
|
812
|
+
<dl>
|
813
|
+
<dt><code>{spawn, Tests}</code></dt>
|
814
|
+
<dd>Runs the specified tests in a separate subprocess, while the current
|
815
|
+
test process waits for it to finish. This is useful for tests that need
|
816
|
+
a fresh, isolated process state. (Note that EUnit always starts at least
|
817
|
+
one such a subprocess automatically; tests are never executed by the
|
818
|
+
caller's own process.)</dd>
|
819
|
+
<dt><code>{spawn, Node::atom(), Tests}</code></dt>
|
820
|
+
<dd>Like <code>{spawn, Tests}</code>, but runs the specified tests on the given
|
821
|
+
Erlang node.</dd>
|
822
|
+
<dt><code>{timeout, Time::number(), Tests}</code></dt>
|
823
|
+
<dd>Runs the specified tests under the given timeout. Time is in
|
824
|
+
seconds; e.g., 60 means one minute and 0.1 means 1/10th of a second. If
|
825
|
+
the timeout is exceeded, the unfinished tests will be forced to
|
826
|
+
terminate. Note that if a timeout is set around a fixture, it includes
|
827
|
+
the time for setup and cleanup, and if the timeout is triggered, the
|
828
|
+
entire fixture is abruptly terminated (without running the
|
829
|
+
cleanup).</dd>
|
830
|
+
<dt><code>{inorder, Tests}</code></dt>
|
831
|
+
<dd>Runs the specified tests in strict order. Also see <code>{inparallel,
|
832
|
+
Tests}</code>. By default, tests are neither marked as <code>inorder</code> or
|
833
|
+
<code>inparallel</code>, but may be executed as the test framework chooses.</dd>
|
834
|
+
<dt><code>{inparallel, Tests}</code></dt>
|
835
|
+
<dd>Runs the specified tests in parallel (if possible). Also see
|
836
|
+
<code>{inorder, Tests}</code>.</dd>
|
837
|
+
<dt><code>{inparallel, N::integer(), Tests}</code></dt>
|
838
|
+
<dd>Like <code>{inparallel, Tests}</code>, but running no more than <code>N</code> subtests
|
839
|
+
simultaneously.</dd>
|
840
|
+
</dl>
|
841
|
+
|
842
|
+
<h4><a name="Fixtures">Fixtures</a></h4>
|
843
|
+
|
844
|
+
<p>A "fixture" is some state that is necessary for a particular set of
|
845
|
+
tests to run. EUnit's support for fixtures makes it easy to set up such
|
846
|
+
state locally for a test set, and automatically tear it down again when
|
847
|
+
the test set is finished, regardless of the outcome (success, failures,
|
848
|
+
timeouts, etc.).</p>
|
849
|
+
|
850
|
+
<p>To make the descriptions simpler, we first list some definitions:
|
851
|
+
<center>
|
852
|
+
<table border="0" cellspacing="4">
|
853
|
+
<tr>
|
854
|
+
<td><code>Setup</code></td><td><code>() -> (R::any())</code></td>
|
855
|
+
</tr>
|
856
|
+
<tr>
|
857
|
+
<td><code>SetupX</code></td><td><code>(X::any()) -> (R::any())</code></td>
|
858
|
+
</tr>
|
859
|
+
<tr>
|
860
|
+
<td><code>Cleanup</code></td><td><code>(R::any()) -> any()</code></td>
|
861
|
+
</tr>
|
862
|
+
<tr>
|
863
|
+
<td><code>CleanupX</code></td><td><code>(X::any(), R::any()) -> any()</code></td>
|
864
|
+
</tr>
|
865
|
+
<tr>
|
866
|
+
<td><code>Instantiator</code></td><td><code>((R::any()) -> Tests) | {with, [AbstractTestFun::((any()) -> any())]}</code></td>
|
867
|
+
</tr>
|
868
|
+
<tr>
|
869
|
+
<td><code>Where</code></td><td><code>local | spawn | {spawn, Node::atom()}</code></td>
|
870
|
+
</tr>
|
871
|
+
</table>
|
872
|
+
</center>
|
873
|
+
(these are explained in more detail further below.)</p>
|
874
|
+
|
875
|
+
The following representations specify fixture handling for test sets:
|
876
|
+
<dl>
|
877
|
+
<dt><code>{setup, Setup, Tests | Instantiator}</code></dt>
|
878
|
+
<dt><code>{setup, Setup, Cleanup, Tests | Instantiator}</code></dt>
|
879
|
+
<dt><code>{setup, Where, Setup, Tests | Instantiator}</code></dt>
|
880
|
+
<dt><code>{setup, Where, Setup, Cleanup, Tests | Instantiator}</code></dt>
|
881
|
+
<dd><code>setup</code> sets up a single fixture for running all of the specified
|
882
|
+
tests, with optional teardown afterwards. The arguments are described in
|
883
|
+
detail below.
|
884
|
+
</dd>
|
885
|
+
<dt><code>{node, Node::atom(), Tests | Instantiator}</code></dt>
|
886
|
+
<dt><code>{node, Node::atom(), Args::string(), Tests | Instantiator}</code></dt>
|
887
|
+
<dd><code>node</code> is like <code>setup</code>, but with a built-in behaviour: it starts a
|
888
|
+
slave node for the duration of the tests. The atom <code>Node</code> should have
|
889
|
+
the format <code>nodename@full.machine.name</code>, and <code>Args</code> are the optional
|
890
|
+
arguments to the new node; see <code>slave:start_link/3</code> for details.
|
891
|
+
</dd>
|
892
|
+
<dt><code>{foreach, Where, Setup, Cleanup, [Tests | Instantiator]}</code></dt>
|
893
|
+
<dt><code>{foreach, Setup, Cleanup, [Tests | Instantiator]}</code></dt>
|
894
|
+
<dt><code>{foreach, Where, Setup, [Tests | Instantiator]}</code></dt>
|
895
|
+
<dt><code>{foreach, Setup, [Tests | Instantiator]}</code></dt>
|
896
|
+
<dd><code>foreach</code> is used to set up a fixture and optionally tear it down
|
897
|
+
afterwards, repeated for each single one of the specified test sets.
|
898
|
+
</dd>
|
899
|
+
<dt><code>{foreachx, Where, SetupX, CleanupX,
|
900
|
+
Pairs::[{X::any(), ((X::any(), R::any()) -> Tests)}]}</code></dt>
|
901
|
+
<dt><code>{foreachx, SetupX, CleanupX, Pairs}</code></dt>
|
902
|
+
<dt><code>{foreachx, Where, SetupX, Pairs}</code></dt>
|
903
|
+
<dt><code>{foreachx, SetupX, Pairs}</code></dt>
|
904
|
+
<dd><code>foreachx</code> is like <code>foreach</code>, but uses a list of pairs, each
|
905
|
+
containing an extra argument <code>X</code> and an extended instantiator function.
|
906
|
+
</dd>
|
907
|
+
</dl>
|
908
|
+
|
909
|
+
<p>A <code>Setup</code> function is executed just before any of the specified tests
|
910
|
+
are run, and a <code>Cleanup</code> function is executed when no more of the
|
911
|
+
specified tests will be run, regardless of the reason. A <code>Setup</code>
|
912
|
+
function takes no argument, and returns some value which will be passed
|
913
|
+
as it is to the <code>Cleanup</code> function. A <code>Cleanup</code> function should do
|
914
|
+
whatever necessary and return some arbitrary value, such as the atom
|
915
|
+
<code>ok</code>. (<code>SetupX</code> and <code>CleanupX</code> functions are similar, but receive one
|
916
|
+
additional argument: some value <code>X</code>, which depends on the context.) When
|
917
|
+
no <code>Cleanup</code> function is specified, a dummy function is used which has
|
918
|
+
no effect.</p>
|
919
|
+
|
920
|
+
<p>An <code>Instantiator</code> function receives the same value as the <code>Cleanup</code>
|
921
|
+
function, i.e., the value returned by the <code>Setup</code> function. It should
|
922
|
+
then behave much like a generator (see <a href="#Primitives">Primitives</a>), and
|
923
|
+
return a test set whose tests have been <em>instantiated</em> with the
|
924
|
+
given value. A special case is the syntax <code>{with, [AbstractTestFun]}</code>
|
925
|
+
which represents an instantiator function that distributes the value
|
926
|
+
over a list of unary functions; see <a href="#Primitives">Primitives</a>: <code>{with, X,
|
927
|
+
[...]}</code> for more details.</p>
|
928
|
+
|
929
|
+
A <code>Where</code> term controls how the specified tests are executed. The
|
930
|
+
default is <code>spawn</code>, which means that the current process handles the
|
931
|
+
setup and teardown, while the tests are executed in a subprocess.
|
932
|
+
<code>{spawn, Node}</code> is like <code>spawn</code>, but runs the subprocess on the
|
933
|
+
specified node. <code>local</code> means that the current process will handle both
|
934
|
+
setup/teardown and running the tests - the drawback is that if a test
|
935
|
+
times out so that the process is killed, the <em>cleanup will not be
|
936
|
+
performed</em>; hence, avoid this for persistent fixtures such as file
|
937
|
+
operations. In general, 'local' should only be used when:
|
938
|
+
<ul>
|
939
|
+
<li>the setup/teardown needs to be executed by the process that will
|
940
|
+
run the tests;</li>
|
941
|
+
<li>no further teardown needs to be done if the process is killed
|
942
|
+
(i.e., no state outside the process was affected by the setup)</li>
|
943
|
+
</ul>
|
944
|
+
|
945
|
+
<h4><a name="Lazy_generators">Lazy generators</a></h4>
|
946
|
+
|
947
|
+
<p>Sometimes, it can be convenient not to produce the whole set of test
|
948
|
+
descriptions before the testing begins; for example, if you want to
|
949
|
+
generate a huge amount of tests that would take up too much space to
|
950
|
+
keep in memory all at once.</p>
|
951
|
+
|
952
|
+
<p>It is fairly easy to write a generator which, each time it is called,
|
953
|
+
either produces an empty list if it is done, or otherwise produces a
|
954
|
+
list containing a single test case plus a new generator which will
|
955
|
+
produce the rest of the tests. This demonstrates the basic pattern:</p>
|
956
|
+
|
957
|
+
<pre> lazy_test_() ->
|
958
|
+
lazy_gen(10000).
|
959
|
+
|
960
|
+
lazy_gen(N) ->
|
961
|
+
{generator,
|
962
|
+
fun () ->
|
963
|
+
if N > 0 ->
|
964
|
+
[?_test(...)
|
965
|
+
| lazy_gen(N-1)];
|
966
|
+
true ->
|
967
|
+
[]
|
968
|
+
end
|
969
|
+
end}.</pre>
|
970
|
+
|
971
|
+
<p>When EUnit traverses the test representation in order to run the tests,
|
972
|
+
the new generator will not be called to produce the next test until the
|
973
|
+
previous test has been executed.</p>
|
974
|
+
|
975
|
+
Note that it is easiest to write this kind of recursive generator using
|
976
|
+
a help function, like the <code>lazy_gen/1</code> function above. It can also be
|
977
|
+
written using a recursive fun, if you prefer to not clutter your
|
978
|
+
function namespace and are comfortable with writing that kind of code.
|
979
|
+
|
980
|
+
<hr>
|
981
|
+
<div class="navbar"><a name="#navbar_bottom"></a><table width="100%" border="0" cellspacing="0" cellpadding="2" summary="navigation bar"><tr><td><a href="overview-summary.html" target="overviewFrame">Overview</a></td><td><a href="http://www.erlang.org/"><img src="erlang.png" align="right" border="0" alt="erlang logo"></a></td></tr></table></div>
|
982
|
+
<p><i>Generated by EDoc, Oct 12 2008, 14:17:27.</i></p>
|
983
|
+
</body>
|
984
|
+
</html>
|