Usage Documentation?

Viewing 5 replies - 1 through 5 (of 5 total)
  • Plugin Author foxly

    (@foxly)

    11 years, 3 months ago

    OMG …people are using our tools! Totally happy!

    1) grab the latest version from github.

    2) We’re too busy to write-up a full set of docs for Razor right now …but its incredibly easy to use:

    a) Make sure PHP is set up so you can just go “php whatever.php<enter>” in the terminal window to run a script.

    b) Then navigate to “/whatever/wp-content/plugins/razor/” and type “php test.php –plugin=plugin_name<enter>” to test a specific plugin.

    3) To add Razor test capabilities to your plugin, create a “plugin_name/unit-test/” folder, and follow the design patterns shown here.

    This is working code, which honestly is a lot more valuable than simple documentation.

    We’ll help you get up to speed on Razor, and even write sample code for your plugin if necessary. WordPress plugins really, really need to adopt unit testing, and we want to make that happen.

    ^C^

    scribu

    (@scribu)

    11 years, 2 months ago

    WordPress plugins really, really need to adopt unit testing, and we want to make that happen.

    Then write some ****ing documentation for WP Razor! It might be brilliant, but people simply won’t invest hours in it, just to figure out if it makes sense to use it, or if they should use the official unit testing suite or what.

    And no, saying “just look at the code” doesn’t cut it. There are a few basic, high-level things that are critical to getting started, which aren’t easy to gleam by looking at the code.

    For example:

    * Do I always need the testplan.php file?

    * Does WP Razor automatically wrap DB queries in a transaction, like the official unit tests do, or do I have to manually clean up the database?

    * How does QUnit fit into all of this?

    These are just off the top of my head.

    I’ve tried to use WP Razor several times, and each time I just gave up, because it seemed too much of a headache to set up. So, I just invented my own system, based on the official testing suite, because it has a basic guide and it doesn’t try to wrap around PHPUnit, so you can just look at PHPUnit’s documentation for details.

    In conclusion, if you really want other people to adopt WP Razor, you have to put up some docs/tutorials/comparisons to get them started.

    Plugin Author foxly

    (@foxly)

    11 years, 2 months ago

    Alright, since there’s clearly some interest in the plugin, we’ll write some documentation.

    To answer your questions:

    Do I always need the testplan.php file?

    Yes. When you call razor using the –plugin=my_plugin option, it looks for the /plugin_name/unit-test/ folder and loads the ‘testplan.php’ file inside it.

    Does WP Razor automatically wrap DB queries in a transaction, like the official unit tests do, or do I have to manually clean up the database?

    No. And I doubt the WP database class wraps queries in a transaction, either.

    1) This would make it impossible to test any MySQL table type other than “InnoDB”.

    2) It would make it impossible to test database queries that involve transactions because MySQL doesn’t support nested transactions.

    3) It would make it much harder to debug queries, because you wouldn’t be able to examine the table state following a test, or if a test crashed mid-test.

    Razor uses a separate database, typically called ‘unit_test’, and loads a WordPress image of your choice into it. Tests are run against this image, and the image persists in the database following a run so that you can examine it if necessary. A fresh image is loaded at the beginning of each run, and you can load a fresh image before a given test if you need to.

    How does QUnit fit into all of this?

    qUnit is used for testing JavaScript used in a plugin’s front-end and admin screens. qUnit tests are currently run from a special page in the plugin’s admin back-end, but we’re probably going to build an engine that runs them using node.js or zombie in the future.

    ^F^

    scribu

    (@scribu)

    11 years, 2 months ago

    And I doubt the WP database class wraps queries in a transaction, either.

    The WPDB class doesn’t, but the test runner does:

    class WP_UnitTestCase extends PHPUnit_Framework_TestCase {

	function setUp() {
		...
		global $wpdb;
		$wpdb->query( 'SET autocommit = 0;' );
		$wpdb->query( 'START TRANSACTION;' );
		...
	}

	function tearDown() {
		global $wpdb;
		$wpdb->query( 'ROLLBACK' );

		...
	}
...

    http://unit-test.svn.wordpress.org/trunk/includes/testcase.php

    PS: Thanks for the answers so far.

    Plugin Author foxly

    (@foxly)

    11 years, 2 months ago

    Well isn’t that clever … 🙂

    I like that strategy. We’ll add it as an option to Razor for developers who don’t use transactions in their test fixtures.

    ^F^

    PS: We’re now writing documentation for Razor. Look for it on Razor’s GitHub Page

Viewing 5 replies - 1 through 5 (of 5 total)
  • The topic ‘Usage Documentation?’ is closed to new replies.