Merge branch 'test-support'

Author: ramitha

packages/@css-blocks/core/src/BlockParser/features/export-blocks.ts

@@ -59,28 +59,29 @@ export async function exportBlocks(block: Block, factory: BlockFactory | BlockFa
           `Malformed block export: \`@export ${atRule.params}\``,
           sourceRange(factory.configuration, block.stylesheet, file, atRule),
         ));
-      }
+      } else {
+        block.blockAST!.children.push(exports);
+        // Import file, then parse file, then save block reference.
+        let srcBlockPromise: Promise<Block> = Promise.resolve(block);
+        if (typeguards.isBlockExport(exports)) {
+          srcBlockPromise = Promise.resolve(factory.getBlockRelative(block.identifier, exports.fromPath));
+        }
 
-      // Import file, then parse file, then save block reference.
-      let srcBlockPromise: Promise<Block> = Promise.resolve(block);
-      if (typeguards.isBlockExport(exports)) {
-        srcBlockPromise = Promise.resolve(factory.getBlockRelative(block.identifier, exports.fromPath));
+        // Validate our imported block name is a valid CSS identifier.
+        const exportPromise = srcBlockPromise.then(
+          (srcBlock) => {
+            validateAndAddBlockExport(block, factory.configuration, srcBlock, remoteNames, exports, file, atRule);
+          },
+          (error) => {
+            block.addError(new errors.CascadingError(
+              `Error in exported block "${(<BlockExport>exports).fromPath}"`,
+              error,
+              sourceRange(factory.configuration, block.stylesheet, file, atRule),
+            ));
+          },
+        );
+        exportPromises.push(exportPromise);
       }
-
-      // Validate our imported block name is a valid CSS identifier.
-      const exportPromise = srcBlockPromise.then(
-        (srcBlock) => {
-          validateAndAddBlockExport(block, factory.configuration, srcBlock, remoteNames, exports, file, atRule);
-        },
-        (error) => {
-          block.addError(new errors.CascadingError(
-            `Error in exported block "${(<BlockExport>exports).fromPath}"`,
-            error,
-            sourceRange(factory.configuration, block.stylesheet, file, atRule),
-          ));
-        },
-      );
-      exportPromises.push(exportPromise);
     });
   }
 
@@ -113,20 +114,22 @@ export function exportBlocksSync(block: Block, factory: BlockFactorySync, file:
           `Malformed block export: \`@export ${atRule.params}\``,
           sourceRange(factory.configuration, block.stylesheet, file, atRule),
         ));
-      }
-
-      // Import file, then parse file, then save block reference.
-      let srcBlock: Block;
-      if (typeguards.isBlockExport(exports)) {
-        try {
-          srcBlock = factory.getBlockRelative(block.identifier, exports.fromPath);
-          validateAndAddBlockExport(block, factory.configuration, srcBlock, remoteNames, exports, file, atRule);
-        } catch (error) {
-          block.addError(new errors.CascadingError(
-            `Error in exported block "${exports.fromPath}"`,
-            error,
-            sourceRange(factory.configuration, block.stylesheet, file, atRule),
-          ));
+      } else {
+        block.blockAST!.children.push(exports);
+
+        // Import file, then parse file, then save block reference.
+        let srcBlock: Block;
+        if (typeguards.isBlockExport(exports)) {
+          try {
+            srcBlock = factory.getBlockRelative(block.identifier, exports.fromPath);
+            validateAndAddBlockExport(block, factory.configuration, srcBlock, remoteNames, exports, file, atRule);
+          } catch (error) {
+            block.addError(new errors.CascadingError(
+              `Error in exported block "${exports.fromPath}"`,
+              error,
+              sourceRange(factory.configuration, block.stylesheet, file, atRule),
+            ));
+          }
         }
       }
     });

packages/@css-blocks/core/test/acceptance/DfnFilesFullWorkflow.ts

@@ -16,10 +16,18 @@ export class AcceptanceTestDefinitionFilesFullWorkflow {
     const compiler = new BlockCompiler(postcss, config);
     compiler.setDefinitionCompiler(blockDfnCompiler);
 
+    imports.registerSource(
+      "/foo/bar/other.block.css",
+      `:scope { color: red; }`,
+    );
+
     // Part 1: Given a basic CSS Blocks source file, generate a definition file.
     imports.registerSource(
       "/foo/bar/source.block.css",
       outdent`
+        @block (default as other) from './other.block.css';
+        @export (other);
+
         :scope { background-color: #FFF; }
         :scope[toggled] { color: #000; }
         :scope[foo="bar"] { border-top-color: #F00; }
@@ -32,7 +40,6 @@ export class AcceptanceTestDefinitionFilesFullWorkflow {
       `,
     );
     const originalBlock = await factory.getBlockFromPath("/foo/bar/source.block.css");
-
     const { css: cssTree, definition: definitionTree } = compiler.compileWithDefinition(originalBlock, originalBlock.stylesheet!, new Set(), "/foo/bar/source.block.d.css");
     const compiledCss = cssTree.toString();
     const definition = definitionTree.toString();
@@ -64,6 +71,8 @@ export class AcceptanceTestDefinitionFilesFullWorkflow {
       `,
       outdent`
         @block-syntax-version 1;
+        @block other from "./other.css";
+        @export (other);
         :scope {
             block-id: "${originalBlock.guid}";
             block-name: "source";
@@ -93,12 +102,19 @@ export class AcceptanceTestDefinitionFilesFullWorkflow {
     imports.reset();
     factory.reset();
 
+    imports.registerSource(
+      "/foo/bar/other.css",
+      `:scope { color: red; }`,
+    );
+
     imports.registerCompiledCssSource(
       "/foo/bar/source.css",
       compiledCss,
       "/foo/bar/source.block.d.css",
       definition,
     );
+
+    await factory.getBlockFromPath("/foo/bar/other.css");
     const reconstitutedBlock = await factory.getBlockFromPath("/foo/bar/source.css");
 
     // And now some checks to validate that we were able to reconstitute accurately.

packages/@css-blocks/ember-app/README.md

@@ -32,6 +32,41 @@ The following options can be passed as options to the `css-blocks` property in y
 * `broccoliConcat` - Options that control the behavior of broccoli-concat, which is used to concatenate CSS files together by ember-app during postprocess. If this is set to false, broccoli-concat will *not* run and you'll need to add additional processing to add the CSS Blocks compiled content to your final CSS build artifact.
 * `appClasses` - List of classes that are used by application CSS and might conflict with the optimizer. You should add any short class names (~5 characters) to this list so the optimizer doesn't use these when building the CSS Blocks compiled output. This is a convenience alias for `optimization.rewriteIdents.omitIdents.class[]`. It has no effect if optimization is disabled.
 
+## Testing
+Once you have integrated this addon within an ember application, all your CSS classnames are going to look very different from what they did in the block files that you had originally written and the output CSS classnames will vary across builds and across different machines. This is done intentionally to ensure that you don't use any CSS classname selectors in any of the tests and that your tests remain robust across executions. Not to mention, even the number of classes on an element can be entirely different after all the CSS has been optimized using opticss.
+
+In order to faciliate testing in such an environment, this ember addon provides a utility method called `setupCSSBlocksTest()` that that exposes the CSS blocks service that can in turn be used to query the existence of certain classes on your elements.
+
+Note: `setupCSSBlocksTest()` has been written to work with `ember-qunit` and `ember-mocha`.
+
+### Test setup and usage
+- In your integration or acceptance tests, call `setupCSSBlocksTest()` declaring any tests. Ensure that `setupCSSBlocksTest()` is called *after* `setupTest|setupRenderingTest|setupApplicationTest` for the setup to work as desired.
+**Note: `setupCSSBlocksTest` is exposed within a service on the application's namespace and will have to be imported as such**
+    ```js
+    import { setupCSSBlocksTest} from '<appName>/services/css-blocks-test-support';
+    ```
+- After this, the css-blocks service is available to the test via `this.cssblocks`
+- The test service primarily exposes a single API function, `this.cssBlocks.getBlock(<pathToBlock>, <blockName>)` that takes in a path to the block file and the an optional blockName. If the blockName isn't specified, the default block for the block file is returned. The <blockPath> begin with either the appName, the addon name (if its from an in-repo addon) or by the engine's name(in the case of an in-repo engine) that it is a part of. `getBlock()` returns a reference to the runtime CSS block which can be queried for styles within the block using `.style(<styleName>)`.
+- The element can then assert whether a certain style is present on it or not using `element.classList.contains()`
+
+Putting it all together in an example,
+```js
+import { setupCSSBlocksTest } from 'my-very-fine-app/services/css-blocks-test-support';
+
+module('Acceptance | css blocks test', function (hooks) {
+  setupApplicationTest(hooks);
+
+  setupCSSBlocksTest(hooks);
+
+  test('visiting /', async function (assert) {
+    await visit('/');
+    let defaultBlock = this.cssBlocks.getBlock("my-very-fine-app/styles/components/application", "default");
+    let element = find('[data-test-large-hello]');
+    assert.ok(element.classList.contains(defaultBlock.style(':scope[size="large]')));
+  });
+});
+```
+
 ## Common Gotchas
 
 This section is devoted to common issues you might run into when working with this addon.

packages/@css-blocks/ember-app/runtime/app/services/TestSupportData.ts

@@ -0,0 +1 @@
+../../../src/TestSupportData.ts

packages/@css-blocks/ember-app/runtime/app/services/css-blocks-test-support.ts

@@ -0,0 +1,115 @@
+/// @ts-ignore
+import { data as _data } from "./-css-blocks-data";
+/// @ts-ignore
+import { testSupportData as _testData } from "./-css-blocks-test-support-data";
+import { AggregateRewriteData } from "./AggregateRewriteData";
+import CSSBlocksService from "./css-blocks";
+import { TestSupportData } from "./TestSupportData";
+
+const testData: TestSupportData = _testData;
+const data: AggregateRewriteData = _data;
+
+export class TestBlock {
+  blockName: string;
+  blockId: string;
+  styles: Array<string>;
+  constructor(blockName: string , blockId: string, styles: Array<string>) {
+    this.blockName = blockName;
+    this.blockId = blockId;
+    this.styles = styles;
+  }
+  style(styleName: string) {
+    if (this.styles.includes(styleName)) {
+      return `${this.blockId}${styleName}`;
+    } else {
+      throw new Error(`No style named "${styleName}" found on "${this.blockName}". Specify one of: ${this.styles.join(", ")}.`);
+    }
+  }
+}
+
+export class CSSBlocksTestService extends CSSBlocksService {
+  constructor() {
+    /// @ts-ignore
+    super(...arguments); // need to pass in ...arguments since "@ember/service" extends from EmberObject
+  }
+
+  classNamesFor(argv: Array<string | number | boolean | null>): string {
+    let runtimeClassNames = super.classNamesFor(argv);
+    let directlyAppliedStyleIds = this.getDirectlyAppliedStyles(argv);
+    // convert the directly applied styleIds into a human readable form
+    let proxyClassNames = this.getStyleNames(directlyAppliedStyleIds).join(" ");
+    return `${proxyClassNames} ${runtimeClassNames}`;
+  }
+
+  /**
+   * Used to query the runtime test data to obtain the block's runtime id from
+   * it's moduleName
+   * @param moduleName name of the node module to look for the block
+   * @param blockName name of the block to find within the moduleName
+   */
+  getBlock(fileName: string, blockName: string): TestBlock {
+    let runtimeBlockName = testData[fileName];
+
+    if (!runtimeBlockName) {
+      throw new Error(`No block file named "${fileName}" found in within this app's namespace`);
+    } else {
+      let runtimeGuid = runtimeBlockName[blockName];
+
+      if (!runtimeGuid) {
+        throw new Error(`No block named "${blockName}" found within "${fileName}". Specify one of: ${Object.keys(runtimeBlockName).join(", ")}.`);
+      }
+      return new TestBlock(blockName, runtimeGuid, getStyles(runtimeGuid));
+    }
+  }
+}
+
+/**
+* Returns the available styles, given the blockGuid
+*/
+function getStyles(guid: string): Array<string> {
+  let blockIndex = data.blockIds[guid];
+  let blockInfo = data.blocks[blockIndex];
+  return Object.keys(blockInfo.blockInterfaceStyles);
+}
+
+/**
+ * This is a utility function that sets up all the testing infra needed for CSS
+ * blocks. It essentially overrides the css-blocks service used by the app
+ * during tests and adds dummy classNames that is more human readable. It exposes
+ * the test API via this.cssBlocks that can be used within the test files themselves.
+ *
+ * This function will work both with `ember-qunit` and with `ember-mocha` since
+ * the ember setup functions do the same for both the libraries.
+ *
+ * Usage within a test
+    module('Acceptance | css blocks helper', function (hooks) {
+      setupApplicationTest(hooks);
+      setupCSSBlocksTest(hooks);
+
+      test('visiting /', async function (assert) {
+        await visit('/');
+        let defaultBlock = this.cssBlocks.getBlock("hue-web-component/styles/components/hue-web-component", "default");
+        let element = find('[data-test-large-hello]');
+        assert.ok(element.classList.contains(defaultBlock.style(':scope[size="large]')));
+      });
+    });
+ */
+// @ts-ignore the error for hooks as this can either come from qunit or mocha
+export function setupCSSBlocksTest(hooks) {
+  hooks.beforeEach(function() {
+    // ember-qunit and ember-mocha sets this.owner and we have to check that one of the
+    // setup functions from there are called before we can register our service
+    // @ts-ignore
+    if (!this.owner) {
+      throw new Error(
+        "setupCSSBlocksTest must be called after setupTest|setupRenderingTest|setupApplicationTest",
+      );
+    }
+
+    // register the CSS blocks service before each test
+    // @ts-ignore
+    this.owner.register("service:css-blocks", CSSBlocksTestService);
+    // @ts-ignore
+    this.cssBlocks = this.owner.lookup("service:css-blocks");
+  });
+}