SCuri*

Automates unit test boilerplate for Angular components/services/directives/etc. It will generate spec for you and help you update it when dependencies are added or removed!

Powered by Schematics and TypeScript compiler

Links

VS Code extension available!

🐱‍👤Need a custom template?

🤙Have some feedback or need a feature? SCuri discussion on github

🤵Need commercial-quality coverage for SCuri?

💵Support us

Why?

After a component has been created it is boring and tedious to do the tests - and we often don't. SCuri* tries to jump-start that by walking the component's constructor, parsing the dependencies and creating mocks for each of them, and then including them in the spec.

Features

Create a test case from scratch

The video shows how to use schematics scuri:spec --name src\app\my-com\my-com.component.ts to create a spec from scratch (if already created see update or use --force to overwrite).

For Angular CLI >= 6 ng g scuri:spec --name src\app\my-com\my-com.component.ts could be used instead.

--name is now optional ng g scuri:spec my-com.component.ts or npx schematics scuri:spec my-com.component.ts

See details down here.

Update existing test

Shows how we begin with an outdated test:

• missing it test case for one of the public methods (getData)
• missing dependency HttpClient to instantiate the component

And after schematics scuri:spec --name src\app\my-com\my-com.component.ts --update command we get the updated test - dependency and a scaffold test case added.

For Angular CLI >= 6 ng g scuri:spec --name src\app\my-com\my-com.component.ts --update could be used instead.

See details down here

AutoSpy

Generates an autoSpy function that takes a type and returns an object with the same type plus all its methods are mocked i.e. jasmine.spy() or jest.fn().

See details down here. Needs tsconfig path setup -> there.

Getting started / Setup

Using VS Code? Just install the SCuri VS Code extension

Command line setup

1. Install deps

   1npm install -D scuri
   2ng g scuri:spec --name src/app/app.component.ts

2. Generate autospy

   1ng g scuri:autospy

   Details and older Angular versions

3. Tell Typescript where to find autoSpy by adding autoSpy to paths:

   1{
   2    ...
   3    "compilerOptions": {
   4        ...
   5        "baseUrl": ".",
   6        "paths": {
   7            "autoSpy": ["./src/auto-spy"]
   8        }
   9    }
   10}

   Details here

4. Start using scuri:

   1ng g scuri:spec --name src/app/app.component.ts

If you get Error: Invalid rule result: Function(). see the troubleshooting section below.

Details

Create spec from scratch

1ng g scuri:spec --name src/app/app.component.ts

or

1npx schematics scuri:spec --name src/app/app.component.ts

Requires --name - an existing .ts file with one class (Component/Service/Directive/etc.) and NONE existing .spec.ts file.

Overwrite existing spec

1ng g scuri:spec --name src/app/app.component.ts --force

or

1npx schematics scuri:spec --name src/app/app.component.ts --force

Requires --name - an existing .ts file with one class (Component/Service/Directive/etc.). Will overwrite any existing .spec.ts file.

This might be useful in certain more complex cases. Using a diff tool one could easily combine the preexisting and newly created (overwritten) content - just like a merge conflict is resolved.

Update existing spec

1ng g scuri:spec --name src/app/app.component.ts --update

or

1npx schematics scuri:spec --name src/app/app.component.ts --update

Requires --name - an existing .ts file with one class (Component/Service/Directive/etc.) and one existing .spec.ts file where the update will happen.

AutoSpy

To generate an auto-spy.ts file with the type and function which can be used for automating mock creation, use:

ng g scuri:autospy

See the Autospy wiki page.

Using older versions of Angular?

• Angular v5, v4, v2: bash npm i -g @angular-devkit/schematics-cli npm i -D scuri schematics scuri:autospy --legacy Notice the --legacy flag. It's required due to typescript being less than 2.8. See flags below

Using Jest

ng g scuri:autospy --for jest

Or

schematics scuri:autospy --for jest

Versions and flags

angular	jest / jasmine	command
2,4,5	jasmine	schematics scuri:autospy --legacy
	jest	schematics scuri:autospy --for jest --legacy
6, 7, 8 and up	jasmine	ng g scuri:autospy
	jest	ng g scuri:autospy --for jest

All Angular versions after and including 6 can use the Angular CLI - ng generate scuri:autospy.

Flags:

• --for with accepted values jest and jasmine (default is jasmine)
• --legacy for generating a type compatible with typescript < 2.8 (namely the conditional types feature)

Examples: ng g scuri:autospy --for jest --legacy would generate a ts<2.8, jest-compatible autoSpy type and function ng g scuri:autospy would generate a ts>2.8, jasmine-compatible autoSpy type and function

Autospy and Typescript

After creating the auto-spy.ts file as a result of the scuri:autospy schematic invocation we need to make sure its properly imported in our tests. To that end and keeping in mind that autoSpy is being imported in the created tests as import { autoSpy } from 'autoSpy';. To make that an actual import one could add this line to tsconfig.json:

1{
2    "compilerOptions": {
3        "baseUrl": ".", // This must be specified if "paths" is.
4        "paths": {
5            "autospy": ["./src/auto-spy"] // This mapping is relative to "baseUrl"
6        }
7    }
8}

This is assuming auto-spy.ts was created inside ./src folder. Edit as appropriate for your specific case.

See here for path details

🛣 Road map ~

• Create spec from scratch (or overwrite existing with --force)
• Update existing spec - add/remove dependencies
• Create one scaffold it test case for each public method
• On Update add it-s for newly added public methods
• Generate autoSpy by scuri:autospy (support jest, jasmine and ts with and w/o conditional types)
• Support traditional Angular cli generated tests (with --update)
  • Add setup function when missing
  • Update dependencies
• Allow configuration via file (.scuri.json)
• (workaround) Import autoSpy function automatically - now imported as import { autoSpy } from 'autoSpy';

S.C.u.r.i. *

What's with the name?

A spec generator schematic - Spec Create Update Read (class - component, service, directive and dependencies) Incorporate (them in the spec generated/updated)

Configuring

Scuri can use configuration from the following list by default (package.json .scurirc .scurirc.json .scurirc.yml .scurirc.yaml scurirc.js scurirc.config.js).

Example package.json

1{
2  "name": "my-app",
3  ...
4  "scuri": {
5      "classTemplate": "src/templates/__specFileName__.template",
6      "functionTemplate": "src/templates/__specFileName__.template"
7  }
8}

Example .scurirc

1{
2    "classTemplate": "src/templates/__specFileName__.template",
3    "functionTemplate": "src/templates/__specFileName__.template"
4}

Custom templates

Head over to the custom template guide or see the short explanation below:

• classTemplate - a location of a custom class template to be used. Here's a gist of starter template that explains what properties are available to the class template
  • starter https://gist.github.com/gparlakov/f299011829e229c9d37cf0cb38506d97
  • issue with a specific example link
• functionTemplate - a location of a custom function template to be used. Here's a gist of a starter template that shows what properties are available to the function template

Troubleshooting

Migrating from 1.1 to 1.2 broke the custom template!

Try using __specFileName__.template for your template name. The __specFileName__ gets interpreted while creating the spec. There are other variables available too - see the custom template guide

Rule result Function

To workaround the Error: Invalid rule result: Function(). install schematics separately and call scuri with that.

1npm install -D scuri
2npm i -g @angular-devkit/schematics-cli
3schematics scuri:spec --name src/app/app.component.ts

or if you don't want to install the schematics cli globally and have npm version 6 and above you can

1npm install -D scuri @angular-devkit/schematics-cli
2npx schematics scuri:spec --name src/app/app.component.ts

Contributing

Link

SCuri for enterprise

Available as part of the Tidelift Subscription

The maintainers of SCuri and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open-source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. Learn more.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Georgi Parlakov 💻 🤔 📖 ⚠️

Tzi Yang 🐛

fgisslen 🐛

danjor 🐛

Dependabot 🚧

OSHistory 🐛 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

Like it?

You like the project and it gives you value? You are considering supporting it? That would be really appreciated!

☕Buy us a coffee