Test Driven Style Guide Development - Angular (4.x and above)
A drop in module to automatically create a living style guide based on the test you write for your components.
Bundle with your favorite build tool and you will automatically get a web app where you can view examples of each component together with associated documentation.
--config - You can send a JSON file with the configurations e.g.: --config ./ui-jar.config.json
Example config file (ui-jar.config.json):
{
"directory":"./projects/",
"includes":[".ts$"],
"watch":true,
"urlPrefix":""
}
--directory (string) - path to app root dir e.g. "./src/app"
--includes (RegExp) - space separated list of files to include e.g. "foo\.ts$ bar\.ts$"
--excludes (RegExp) - space separated list of files to exclude e.g. "a\.component\.ts$ b\.component\.ts$"
--url-prefix (string) - add prefix to all urls in UI-jar, e.g. "project-a/styleguide".
--watch - enable watch-mode, UI-jar will watch on file changes in your test files.
Configuration
Add a entry point to your ui-jar app, e.g ui-jar.ts.
Bundle with your favorite build tool (use the same configuration as your regular app, but with ui-jar.ts as the entry point).
AoT-build is not supported yet.
Add a JSDoc-comment to your component containing "@group GROUP_NAME" and
"@component COMPONENT_DISPLAY_NAME".
@group is used to group your components in UI-jar navigation. @component is used as display name of the component in UI-jar.
Description is not required, add if you like. It will be displayed together with your component in UI-jar.
Source code
import{Component,Input}from'@angular/core';
/**
* @group Forms
* @component Checkbox
* @description
* <div>It's possible use <b>html</b> in the description</div>
*/
@Component({
selector:'x-checkbox',
templateUrl:'./checkbox.component.html',
styleUrls:['./checkbox.component.scss']
})
exportclassCheckboxComponent{
@Input('isDisabled') isDisabled: boolean =false;
label: string ='Item A';
...
}
Test code
Add a JSDoc-comment with "@uijar COMPONENT_CLASS_NAME" together with a variable that defines test module definition.
In the example below it's defined in "beforeEach".
Also add a JSDoc-comment containing "@uijarexample" to each test you would like to add as a example in UI-jar.
It's possible to use multiple examples.
/** @uijarexample Add custom title to example here */
it('should create component with "isDisabled" set to true',()=>{
fixture.componentInstance.isDisabled=true;
fixture.componentInstance.label='Item A';
...
});
/** @uijarexample Add custom title to example here */
it('should create component with "isDisabled" set to false',()=>{
fixture.componentInstance.isDisabled=false;
fixture.componentInstance.label='Item A';
...
});
});
Example usage (with test host component)
Source code
import{Component}from'@angular/core';
/**
* @group Buttons & indicators
* @component Buttons
*/
@Component({
selector:'button[buttonA]',
template:'<ng-content></ng-content>',
styleUrls:['./button.scss']
})
exportclassButtonComponent{
...
}
Test code
Sometimes you want to create a test host component for your tests.
It's possible to view test host components in UI-jar, just add "@hostcomponent HOST_COMPONENT_CLASS_NAME" to the JSDoc-comment where you define your module definition.
In the example below it's defined in "beforeEach".
Example usage (with multiple test host components)
Source code
import{Component}from'@angular/core';
/**
* @group Buttons & indicators
* @component Buttons
*/
@Component({
selector:'button[buttonA]',
template:'<ng-content></ng-content>',
styleUrls:['./button.scss']
})
exportclassButtonComponent{
...
}
Test code
Sometimes you want to create multiple test host components for your tests.
It's possible to view multiple test host components in UI-jar, just add "@hostcomponent HOST_COMPONENT_CLASS_NAME" to the JSDoc-comment where you have your "@uijarexample"-comment.
Notice the use of "HttpClientTestingModule" and "HttpTestingController".
UI-jar will automatically detect each requests you would like to fake for a specified resource if you use "expectOne" on "HttpTestingController". Use "flush" and "error" on "TestRequest" to manage which result you would like to have on your requests.
Example usage (add more details about your component)
UI-jar also automatically create a API documentation for your component.
The documentation view all public methods and properties on each component.
It's possible to add more details by adding a JSDoc-comment together with associated method or property.
In the example below, we are adding more details about "isDisabled" property.
Source code
import{Component,Input}from'@angular/core';
/**
* @group Forms
* @component Checkbox
*/
@Component({
selector:'x-checkbox',
templateUrl:'./checkbox.component.html',
styleUrls:['./checkbox.component.scss']
})
exportclassCheckboxComponent{
/** Indicates whether checkbox is disabled or not */