@wordpress/style-engine 0.16.0 → 1.0.0

package/phpunit/class-wp-style-engine-css-rules-store-test.php

@@ -6,63 +6,93 @@
  * @subpackage style-engine
  */
 
-require __DIR__ . '/../class-wp-style-engine-css-rules-store.php';
-require __DIR__ . '/../class-wp-style-engine-css-rule.php';
-require __DIR__ . '/../class-wp-style-engine-css-declarations.php';
+// Check for the existence of Style Engine classes and methods.
+// Once the Style Engine has been migrated to Core we can remove the if statements and require imports.
+// Testing new features from the Gutenberg package may require
+// testing against `gutenberg_` and `_Gutenberg` functions and methods in the future.
+if ( ! class_exists( 'WP_Style_Engine_CSS_Declarations' ) ) {
+	require __DIR__ . '/../class-wp-style-engine-css-declarations.php';
+}
+
+if ( ! class_exists( 'WP_Style_Engine_CSS_Rule' ) ) {
+	require __DIR__ . '/../class-wp-style-engine-css-rule.php';
+}
+
+if ( ! class_exists( 'WP_Style_Engine_CSS_Rules_Store' ) ) {
+	require __DIR__ . '/../class-wp-style-engine-css-rules-store.php';
+}
 
 /**
- * Tests for registering, storing and retrieving CSS Rules.
+ * Tests for registering, storing and retrieving a collection of CSS Rules (a store).
+ *
+ * @coversDefaultClass WP_Style_Engine_CSS_Rules_Store
  */
 class WP_Style_Engine_CSS_Rules_Store_Test extends WP_UnitTestCase {
 	/**
-	 * Tear down after each test.
+	 * Cleans up stores after each test.
 	 */
 	public function tear_down() {
-		parent::tear_down();
 		WP_Style_Engine_CSS_Rules_Store::remove_all_stores();
+		parent::tear_down();
 	}
+
 	/**
-	 * Should create a new store.
+	 * Tests creating a new store on instantiation.
+	 *
+	 * @covers ::__construct
 	 */
-	public function test_create_new_store() {
+	public function test_should_create_new_store_on_instantiation() {
 		$new_pancakes_store = WP_Style_Engine_CSS_Rules_Store::get_store( 'pancakes-with-strawberries' );
+
 		$this->assertInstanceOf( 'WP_Style_Engine_CSS_Rules_Store', $new_pancakes_store );
 	}
 
 	/**
-	 * Should not create a new store with invalid $store_name.
+	 * Tests that a `$store_name` argument is required and no store will be created without one.
+	 *
+	 * @covers ::get_store
 	 */
-	public function test_store_name_required() {
+	public function test_should_not_create_store_without_a_store_name() {
 		$not_a_store = WP_Style_Engine_CSS_Rules_Store::get_store( '' );
-		$this->assertEmpty( $not_a_store );
+
+		$this->assertEmpty( $not_a_store, 'get_store() did not return an empty value with empty string as argument.' );
 
 		$also_not_a_store = WP_Style_Engine_CSS_Rules_Store::get_store( 123 );
-		$this->assertEmpty( $also_not_a_store );
+
+		$this->assertEmpty( $also_not_a_store, 'get_store() did not return an empty value with number as argument.' );
 
 		$definitely_not_a_store = WP_Style_Engine_CSS_Rules_Store::get_store( null );
-		$this->assertEmpty( $definitely_not_a_store );
+
+		$this->assertEmpty( $definitely_not_a_store, 'get_store() did not return an empty value with `null` as argument.' );
 	}
 
 	/**
-	 * Should return previously created store when the same selector key is passed.
+	 * Tests returning a previously created store when the same selector key is passed.
+	 *
+	 * @covers ::get_store
 	 */
-	public function test_get_store() {
+	public function test_should_return_existing_store() {
 		$new_fish_store = WP_Style_Engine_CSS_Rules_Store::get_store( 'fish-n-chips' );
 		$selector       = '.haddock';
 
-		$new_fish_store->add_rule( $selector )->get_selector();
-		$this->assertEquals( $selector, $new_fish_store->add_rule( $selector )->get_selector() );
+		$new_fish_store->add_rule( $selector );
+
+		$this->assertSame( $selector, $new_fish_store->add_rule( $selector )->get_selector(), 'Selector string of store rule does not match expected value' );
 
 		$the_same_fish_store = WP_Style_Engine_CSS_Rules_Store::get_store( 'fish-n-chips' );
-		$this->assertEquals( $selector, $the_same_fish_store->add_rule( $selector )->get_selector() );
+
+		$this->assertSame( $selector, $the_same_fish_store->add_rule( $selector )->get_selector(), 'Selector string of existing store rule does not match expected value' );
 	}
 
 	/**
-	 * Should return all previously created stores.
+	 * Tests returning all previously created stores.
+	 *
+	 * @covers ::get_stores
 	 */
-	public function test_get_stores() {
+	public function test_should_get_all_existing_stores() {
 		$burrito_store    = WP_Style_Engine_CSS_Rules_Store::get_store( 'burrito' );
 		$quesadilla_store = WP_Style_Engine_CSS_Rules_Store::get_store( 'quesadilla' );
+
 		$this->assertEquals(
 			array(
 				'burrito'    => $burrito_store,
@@ -73,34 +103,43 @@ class WP_Style_Engine_CSS_Rules_Store_Test extends WP_UnitTestCase {
 	}
 
 	/**
-	 * Should delete all previously created stores.
+	 * Tests that all previously created stores are deleted.
+	 *
+	 * @covers ::remove_all_stores
 	 */
-	public function test_remove_all_stores() {
+	public function test_should_remove_all_stores() {
 		$dolmades_store = WP_Style_Engine_CSS_Rules_Store::get_store( 'dolmades' );
 		$tzatziki_store = WP_Style_Engine_CSS_Rules_Store::get_store( 'tzatziki' );
+
 		$this->assertEquals(
 			array(
 				'dolmades' => $dolmades_store,
 				'tzatziki' => $tzatziki_store,
 			),
-			WP_Style_Engine_CSS_Rules_Store::get_stores()
+			WP_Style_Engine_CSS_Rules_Store::get_stores(),
+			'Return value of get_stores() does not match expectation'
 		);
 		WP_Style_Engine_CSS_Rules_Store::remove_all_stores();
+
 		$this->assertEquals(
 			array(),
-			WP_Style_Engine_CSS_Rules_Store::get_stores()
+			WP_Style_Engine_CSS_Rules_Store::get_stores(),
+			'Return value of get_stores() is not an empty array after remove_all_stores() called.'
 		);
 	}
 
 	/**
-	 * Should return a stored rule.
+	 * Tests adding rules to an existing store.
+	 *
+	 * @covers ::add_rule
 	 */
-	public function test_add_rule() {
+	public function test_should_add_rule_to_existing_store() {
 		$new_pie_store = WP_Style_Engine_CSS_Rules_Store::get_store( 'meat-pie' );
 		$selector      = '.wp-block-sauce a:hover';
 		$store_rule    = $new_pie_store->add_rule( $selector );
 		$expected      = '';
-		$this->assertEquals( $expected, $store_rule->get_css() );
+
+		$this->assertSame( $expected, $store_rule->get_css(), 'Return value of get_css() is not a empty string where a rule has no CSS declarations.' );
 
 		$pie_declarations = array(
 			'color'         => 'brown',
@@ -112,13 +151,16 @@ class WP_Style_Engine_CSS_Rules_Store_Test extends WP_UnitTestCase {
 
 		$store_rule = $new_pie_store->add_rule( $selector );
 		$expected   = "$selector{{$css_declarations->get_declarations_string()}}";
-		$this->assertEquals( $expected, $store_rule->get_css() );
+
+		$this->assertSame( $expected, $store_rule->get_css(), 'Return value of get_css() does not match expected CSS from existing store rules.' );
 	}
 
 	/**
-	 * Should return all stored rules.
+	 * Tests that all stored rule objects are returned.
+	 *
+	 * @covers ::get_all_rules
 	 */
-	public function test_get_all_rules() {
+	public function test_should_get_all_rule_objects_for_a_store() {
 		$new_pizza_store = WP_Style_Engine_CSS_Rules_Store::get_store( 'pizza-with-mozzarella' );
 		$selector        = '.wp-block-anchovies a:hover';
 		$store_rule      = $new_pizza_store->add_rule( $selector );
@@ -126,33 +168,7 @@ class WP_Style_Engine_CSS_Rules_Store_Test extends WP_UnitTestCase {
 			$selector => $store_rule,
 		);
 
-		$this->assertEquals( $expected, $new_pizza_store->get_all_rules() );
-
-		$pizza_declarations = array(
-			'color'         => 'red',
-			'border-color'  => 'yellow',
-			'border-radius' => '10rem',
-		);
-		$css_declarations   = new WP_Style_Engine_CSS_Declarations( $pizza_declarations );
-		$store_rule->add_declarations( array( $css_declarations ) );
-
-		$expected = array(
-			$selector => $store_rule,
-		);
-		$this->assertEquals( $expected, $new_pizza_store->get_all_rules() );
-
-		$new_pizza_declarations = array(
-			'color'        => 'red',
-			'border-color' => 'red',
-			'font-size'    => '10rem',
-		);
-		$css_declarations       = new WP_Style_Engine_CSS_Declarations( $new_pizza_declarations );
-		$store_rule->add_declarations( array( $css_declarations ) );
-
-		$expected = array(
-			$selector => $store_rule,
-		);
-		$this->assertEquals( $expected, $new_pizza_store->get_all_rules() );
+		$this->assertSame( $expected, $new_pizza_store->get_all_rules(), 'Return value for get_all_rules() does not match expectations.' );
 
 		$new_selector             = '.wp-block-mushroom a:hover';
 		$newer_pizza_declarations = array(
@@ -166,6 +182,7 @@ class WP_Style_Engine_CSS_Rules_Store_Test extends WP_UnitTestCase {
 			$selector     => $store_rule,
 			$new_selector => $new_store_rule,
 		);
-		$this->assertEquals( $expected, $new_pizza_store->get_all_rules() );
+
+		$this->assertSame( $expected, $new_pizza_store->get_all_rules(), 'Return value for get_all_rules() does not match expectations after adding new rules to store.' );
 	}
 }

package/phpunit/class-wp-style-engine-processor-test.php

@@ -1,23 +1,44 @@
 <?php
 /**
- * Tests the Style Engine Renderer class.
+ * Tests the Style Engine Processor class.
  *
  * @package    Gutenberg
  * @subpackage style-engine
  */
-require __DIR__ . '/../class-wp-style-engine-css-rules-store.php';
-require __DIR__ . '/../class-wp-style-engine-css-rule.php';
-require __DIR__ . '/../class-wp-style-engine-css-declarations.php';
-require __DIR__ . '/../class-wp-style-engine-processor.php';
+
+// Check for the existence of Style Engine classes and methods.
+// Once the Style Engine has been migrated to Core we can remove the if statements and require imports.
+// Testing new features from the Gutenberg package may require
+// testing against `gutenberg_` and `_Gutenberg` functions and methods in the future.
+if ( ! class_exists( 'WP_Style_Engine_Processor' ) ) {
+	require __DIR__ . '/../class-wp-style-engine-processor.php';
+}
+
+if ( ! class_exists( 'WP_Style_Engine_CSS_Declarations' ) ) {
+	require __DIR__ . '/../class-wp-style-engine-css-declarations.php';
+}
+
+if ( ! class_exists( 'WP_Style_Engine_CSS_Rule' ) ) {
+	require __DIR__ . '/../class-wp-style-engine-css-rule.php';
+}
+
+if ( ! class_exists( 'WP_Style_Engine_CSS_Rules_Store' ) ) {
+	require __DIR__ . '/../class-wp-style-engine-css-rules-store.php';
+}
 
 /**
  * Tests for compiling and rendering styles from a store of CSS rules.
+ *
+ * @coversDefaultClass WP_Style_Engine_Processor
  */
 class WP_Style_Engine_Processor_Test extends WP_UnitTestCase {
 	/**
-	 * Should compile CSS rules.
+	 * Tests adding rules and returning compiled CSS rules.
+	 *
+	 * @covers ::add_rules
+	 * @covers ::get_css
 	 */
-	public function test_return_rules_as_css() {
+	public function test_should_return_rules_as_compiled_css() {
 		$a_nice_css_rule = new WP_Style_Engine_CSS_Rule( '.a-nice-rule' );
 		$a_nice_css_rule->add_declarations(
 			array(
@@ -35,16 +56,19 @@ class WP_Style_Engine_Processor_Test extends WP_UnitTestCase {
 		);
 		$a_nice_processor = new WP_Style_Engine_Processor();
 		$a_nice_processor->add_rules( array( $a_nice_css_rule, $a_nicer_css_rule ) );
-		$this->assertEquals(
+
+		$this->assertSame(
 			'.a-nice-rule{color:var(--nice-color);background-color:purple;}.a-nicer-rule{font-family:Nice sans;font-size:1em;background-color:purple;}',
 			$a_nice_processor->get_css( array( 'prettify' => false ) )
 		);
 	}
 
 	/**
-	 * Should compile CSS rules.
+	 * Tests compiling CSS rules and formatting them with new lines and indents.
+	 *
+	 * @covers ::get_css
 	 */
-	public function test_return_prettified_rules_as_css() {
+	public function test_should_return_prettified_css_rules() {
 		$a_wonderful_css_rule = new WP_Style_Engine_CSS_Rule( '.a-wonderful-rule' );
 		$a_wonderful_css_rule->add_declarations(
 			array(
@@ -81,16 +105,18 @@ class WP_Style_Engine_Processor_Test extends WP_UnitTestCase {
 	background-color: orange;
 }
 ';
-		$this->assertEquals(
+		$this->assertSame(
 			$expected,
 			$a_wonderful_processor->get_css( array( 'prettify' => true ) )
 		);
 	}
 
 	/**
-	 * Should compile CSS rules from the store.
+	 * Tests adding a store and compiling CSS rules from that store.
+	 *
+	 * @covers ::add_store
 	 */
-	public function test_return_store_rules_as_css() {
+	public function test_should_return_store_rules_as_css() {
 		$a_nice_store = WP_Style_Engine_CSS_Rules_Store::get_store( 'nice' );
 		$a_nice_store->add_rule( '.a-nice-rule' )->add_declarations(
 			array(
@@ -107,16 +133,19 @@ class WP_Style_Engine_Processor_Test extends WP_UnitTestCase {
 		);
 		$a_nice_renderer = new WP_Style_Engine_Processor();
 		$a_nice_renderer->add_store( $a_nice_store );
-		$this->assertEquals(
+		$this->assertSame(
 			'.a-nice-rule{color:var(--nice-color);background-color:purple;}.a-nicer-rule{font-family:Nice sans;font-size:1em;background-color:purple;}',
 			$a_nice_renderer->get_css( array( 'prettify' => false ) )
 		);
 	}
 
 	/**
-	 * Should merge CSS declarations.
+	 * Tests that CSS declarations are merged and deduped in the final CSS rules output.
+	 *
+	 * @covers ::add_rules
+	 * @covers ::get_css
 	 */
-	public function test_dedupe_and_merge_css_declarations() {
+	public function test_should_dedupe_and_merge_css_declarations() {
 		$an_excellent_rule      = new WP_Style_Engine_CSS_Rule( '.an-excellent-rule' );
 		$an_excellent_processor = new WP_Style_Engine_Processor();
 		$an_excellent_rule->add_declarations(
@@ -136,9 +165,10 @@ class WP_Style_Engine_Processor_Test extends WP_UnitTestCase {
 			)
 		);
 		$an_excellent_processor->add_rules( $another_excellent_rule );
-		$this->assertEquals(
+		$this->assertSame(
 			'.an-excellent-rule{color:var(--excellent-color);border-style:dotted;border-color:brown;}',
-			$an_excellent_processor->get_css( array( 'prettify' => false ) )
+			$an_excellent_processor->get_css( array( 'prettify' => false ) ),
+			'Return value of get_css() does not match expectations with new, deduped and merged declarations.'
 		);
 
 		$yet_another_excellent_rule = new WP_Style_Engine_CSS_Rule( '.an-excellent-rule' );
@@ -150,16 +180,19 @@ class WP_Style_Engine_Processor_Test extends WP_UnitTestCase {
 			)
 		);
 		$an_excellent_processor->add_rules( $yet_another_excellent_rule );
-		$this->assertEquals(
+		$this->assertSame(
 			'.an-excellent-rule{color:var(--excellent-color);border-style:dashed;border-color:brown;border-width:2px;}',
-			$an_excellent_processor->get_css( array( 'prettify' => false ) )
+			$an_excellent_processor->get_css( array( 'prettify' => false ) ),
+			'Return value of get_css() does not match expectations with deduped and merged declarations.'
 		);
 	}
 
 	/**
-	 * Should print out uncombined selectors duplicate CSS rules.
+	 * Tests printing out 'unoptimized' CSS, that is, uncombined selectors and duplicate CSS rules.
+	 *
+	 * @covers ::get_css
 	 */
-	public function test_output_verbose_css_rules() {
+	public function test_should_not_optimize_css_output() {
 		$a_sweet_rule = new WP_Style_Engine_CSS_Rule(
 			'.a-sweet-rule',
 			array(
@@ -187,7 +220,7 @@ class WP_Style_Engine_Processor_Test extends WP_UnitTestCase {
 		$a_sweet_processor = new WP_Style_Engine_Processor();
 		$a_sweet_processor->add_rules( array( $a_sweet_rule, $a_sweeter_rule, $the_sweetest_rule ) );
 
-		$this->assertEquals(
+		$this->assertSame(
 			'.a-sweet-rule{color:var(--sweet-color);background-color:purple;}#an-even-sweeter-rule > marquee{color:var(--sweet-color);background-color:purple;}.the-sweetest-rule-of-all a{color:var(--sweet-color);background-color:purple;}',
 			$a_sweet_processor->get_css(
 				array(
@@ -199,9 +232,11 @@ class WP_Style_Engine_Processor_Test extends WP_UnitTestCase {
 	}
 
 	/**
-	 * Should combine duplicate CSS rules.
+	 * Tests that 'optimized' CSS is output, that is, that duplicate CSS rules are combined under their corresponding selectors.
+	 *
+	 * @covers ::get_css
 	 */
-	public function test_combine_css_rules() {
+	public function test_should_optimize_css_output_by_default() {
 		$a_sweet_rule = new WP_Style_Engine_CSS_Rule(
 			'.a-sweet-rule',
 			array(
@@ -221,15 +256,18 @@ class WP_Style_Engine_Processor_Test extends WP_UnitTestCase {
 		$a_sweet_processor = new WP_Style_Engine_Processor();
 		$a_sweet_processor->add_rules( array( $a_sweet_rule, $a_sweeter_rule ) );
 
-		$this->assertEquals(
+		$this->assertSame(
 			'.a-sweet-rule,#an-even-sweeter-rule > marquee{color:var(--sweet-color);background-color:purple;}',
 			$a_sweet_processor->get_css( array( 'prettify' => false ) )
 		);
 	}
-		/**
-		 * Should combine and store CSS rules.
-		 */
-	public function test_combine_previously_added_css_rules() {
+
+	/**
+	 * Tests that incoming CSS rules are merged with existing CSS rules.
+	 *
+	 * @covers ::add_rules
+	 */
+	public function test_should_combine_previously_added_css_rules() {
 		$a_lovely_processor = new WP_Style_Engine_Processor();
 		$a_lovely_rule      = new WP_Style_Engine_CSS_Rule(
 			'.a-lovely-rule',
@@ -245,7 +283,11 @@ class WP_Style_Engine_Processor_Test extends WP_UnitTestCase {
 			)
 		);
 		$a_lovely_processor->add_rules( $a_lovelier_rule );
-		$this->assertEquals( '.a-lovely-rule,.a-lovelier-rule{border-color:purple;}', $a_lovely_processor->get_css( array( 'prettify' => false ) ) );
+		$this->assertSame(
+			'.a-lovely-rule,.a-lovelier-rule{border-color:purple;}',
+			$a_lovely_processor->get_css( array( 'prettify' => false ) ),
+			'Return value of get_css() does not match expectations when combining 2 CSS rules'
+		);
 
 		$a_most_lovely_rule = new WP_Style_Engine_CSS_Rule(
 			'.a-most-lovely-rule',
@@ -263,9 +305,10 @@ class WP_Style_Engine_Processor_Test extends WP_UnitTestCase {
 		);
 		$a_lovely_processor->add_rules( $a_perfectly_lovely_rule );
 
-		$this->assertEquals(
+		$this->assertSame(
 			'.a-lovely-rule,.a-lovelier-rule,.a-most-lovely-rule,.a-perfectly-lovely-rule{border-color:purple;}',
-			$a_lovely_processor->get_css( array( 'prettify' => false ) )
+			$a_lovely_processor->get_css( array( 'prettify' => false ) ),
+			'Return value of get_css() does not match expectations when combining 4 CSS rules'
 		);
 	}
 }