Skip to content

Commit dd22e27

Browse files
janoshrubosjanoshrubos
committed
docs: development workflow
1 parent 00eae51 commit dd22e27

File tree

1 file changed

+296
-6
lines changed

1 file changed

+296
-6
lines changed

‎development-workflow.md

Lines changed: 296 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ You can also use the `--template` flag with the `ns create` command to target a
2222
ns create HelloWorld --template @nativescript/template-hello-world-ts
2323
```
2424

25-
Here you’re passing two things to the `create` command: `HelloWorld` which determines the name of the app you are creating, and the `--template` option, which tells the NativeScript CLI to scaffold an app using a predefined template named “@nativescript/template-hello-world-ts” found [here](https://github.com/NativeScript/nativescript-app-templates/tree/master/packages/template-blank-ts)
25+
Here you’re passing two things to the `create` command: `HelloWorld` which determines the name of the app you are creating, and the `--template` option, which tells the NativeScript CLI to scaffold an app using a predefined template named `@nativescript/template-hello-world-ts` found [here](https://github.com/NativeScript/nativescript-app-templates/tree/master/packages/template-blank-ts)
2626

2727
For a full list of the templates you can use, see the [full list here](https://github.com/NativeScript/nativescript-app-templates/tree/master/packages)
2828

@@ -348,15 +348,305 @@ Alternatively, once you have the NativeScript project built, you can open open t
348348
349349
## Testing
350350
351-
- [REFERENCE] https://github.com/NativeScript/docs/blob/master/docs/tooling/testing/testing.md
352-
- https://github.com/NativeScript/docs/tree/master/docs/tooling/testing/end-to-end-testing
353-
354-
* `ns test ios`
351+
- [USED REFERENCE] https://github.com/NativeScript/docs/blob/master/docs/tooling/testing/testing.md
352+
- [REFERENCE] https://github.com/NativeScript/docs/tree/master/docs/tooling/testing/end-to-end-testing
355353
356354
::: warning Note
357355
Be sure you have prepare/built/run the app at least once before starting the unit test runner.
358356
:::
359357
358+
For more information about end-to-end testing, see [`@nativescript/detox` plugin](detox).
359+
360+
When you develop new features inside your app, you can ensure that they are working properly and that past functionality has not regressed by writing and executing unit tests on a regular basis. With the NativeScript CLI, you can write and execute unit tests using [Jasmine](http://jasmine.github.io/), [Mocha](https://mochajs.org/) with [Chai](http://chaijs.com/) or [QUnit](https://qunitjs.com/).
361+
362+
To run your unit tests, the NativeScript CLI uses [Karma](http://karma-runner.github.io/latest/index.html).
363+
364+
### Before You Begin
365+
366+
Before writing and running unit tests, verify that you have completed the following steps.
367+
368+
1. [Install and configure the NativeScript CLI on your system.]({% slug quick-start %}#the-nativescript-cli)
369+
1. If you don't have any projects, create a new project and navigate to the directory of the newly created directory.
370+
371+
```Shell
372+
ns create projectName
373+
cd projectName
374+
```
375+
376+
1. If you want to create tests for an existing directory, navigate to the directory of the project.
377+
378+
```Shell
379+
cd existingProjectDirectory
380+
```
381+
382+
> **TIP:** You don't need to explicitly add the platforms for which you want to test your project. The NativeScript CLI will configure your project when you begin to run your tests.
383+
384+
### Configure Your Project
385+
386+
The NativeScript CLI lets you choose between three widely popular unit testing frameworks: [Jasmine](http://jasmine.github.io/), [Mocha](https://mochajs.org/) with [Chai](http://chaijs.com/) and [QUnit](https://qunitjs.com/). You need to configure the project for unit testing by choosing a framework. You can use only one framework at a time.
387+
388+
To initialize your project for unit testing, run the following command and, when prompted, use the keyboard arrows to select the framework that you want to use.
389+
390+
```Shell
391+
ns test init
392+
```
393+
394+
This operation applies the following changes to your project.
395+
396+
- It creates the `app/tests` directory. You need to store all tests in this directory. This directory is excluded from release builds.
397+
- It creates an `example.js` file in the `app/tests` directory. This sample test illustrates the basic syntax for the selected framework.
398+
- It installs the nativescript-unit-test-runner npm module for the selected framework and its dev dependencies in `node_modules`.
399+
- It creates `karma.conf.js` in the root of your project. This file contains the default configuration for the Karma server for the selected framework.
400+
401+
> **Note**: To enable and write unit tests for TypeScript or Angular project install the TypeScript typings for the selected testing framework.
402+
403+
```Jasmine
404+
npm i @types/jasmine --save-dev
405+
```
406+
407+
```Mocha
408+
npm i @types/mocha --save-dev
409+
```
410+
411+
```QUnit
412+
npm i @types/qunit --save-dev
413+
```
414+
415+
### Write Your Tests
416+
417+
With the NativeScript CLI, you can extensively test **all JavaScript-related functionality**. You cannot test styling and UI which are not applied or created via JavaScript.
418+
419+
When creating tests for a new or existing functionality, keep in mind the following specifics.
420+
421+
- You need to create your tests as JavaScript files in the `app/tests` directory. The NativeScript CLI recognizes JavaScript files stored in `app/tests` as unit tests.
422+
- You need to write tests which comply with the testing framework specification you have chosen for the project.
423+
- You need to export the functionality that you want to test in the code of your NativeScript project.
424+
- You need to require the module which exposes the functionality that you want to test in the code of your unit tests.
425+
426+
When creating tests for a new or existing functionality, keep in mind the following limitations.
427+
428+
- You cannot require the file or module in which `application.start()` is called.
429+
- You cannot use more than one testing framework per project.
430+
- You cannot test styling and UI which are not applied or created via JavaScript.
431+
432+
The following samples test the initial value of the counter and the message in the Hello World template. These tests show the specifics and limitations outlined above.
433+
434+
```Jasmine
435+
var mainViewModel = require("../main-view-model"); //Require the main view model to expose the functionality inside it.
436+
437+
describe("Hello World Sample Test:", function() {
438+
it("Check counter.", function() {
439+
expect(mainViewModel.createViewModel().counter).toEqual(42); //Check if the counter equals 42.
440+
});
441+
it("Check message.", function () {
442+
expect(mainViewModel.createViewModel().message).toBe("42 taps left"); //Check if the message is "42 taps left".
443+
});
444+
});
445+
```
446+
447+
```Jasmine
448+
// (Angular w/TypeScript)
449+
// As our intention is to test an Angular component that contains annotations
450+
// we need to include the reflect-metadata dependency.
451+
import "reflect-metadata";
452+
453+
// A sample Jasmine test
454+
describe("A suite", function() {
455+
it("contains spec with an expectation", function() {
456+
expect(true).toBe(true);
457+
});
458+
});
459+
```
460+
461+
```Mocha
462+
var mainViewModel = require("../main-view-model"); //Require the main view model to expose the functionality inside it.
463+
464+
describe('Hello World Sample Test:', function () {
465+
it('Counter should be 42 on start.', function () {
466+
assert.equal(mainViewModel.createViewModel().counter, 42); //Assert that the counter equals 42.
467+
});
468+
it('Message should be "42 taps left" on start.', function () {
469+
assert.equal(mainViewModel.createViewModel().message, "42 taps left"); //Assert that the message is "42 taps left".
470+
});
471+
});
472+
```
473+
474+
```QUnit
475+
var mainViewModel = require("../main-view-model"); //Require the main view model to expose the functionality inside it.
476+
477+
QUnit.test("Hello World Sample Test:", function (assert) {
478+
assert.equal( mainViewModel.createViewModel().counter, 42, "Counter, 42; equal succeeds." ); //Assert that the counter equals 42.
479+
assert.equal( mainViewModel.createViewModel().message, "42 taps left", "Message, 42 taps left; equal succeeds." ); //Assert that the message is "42 taps left".
480+
});
481+
```
482+
483+
### Angular TestBed Integration
484+
485+
To use TestBed you have to alter your `karma.conf.js` to:
486+
487+
```
488+
// list of files / patterns to load in the browser
489+
files: [
490+
'src/tests/setup.ts',
491+
'src/tests/**/*.spec.ts'
492+
],
493+
494+
```
495+
496+
The file `src/tests/setup.ts` should look like this for jasmine:
497+
498+
```
499+
import "nativescript-angular/zone-js/testing.jasmine";
500+
import {nsTestBedInit} from "nativescript-angular/testing";
501+
nsTestBedInit();
502+
503+
```
504+
505+
or if using mocha:
506+
507+
```
508+
import "nativescript-angular/zone-js/testing.mocha";
509+
import {nsTestBedInit} from "nativescript-angular/testing";
510+
nsTestBedInit();
511+
512+
```
513+
514+
Then you can use it within the spec files, e.g. `example.spec.ts`:
515+
516+
```
517+
import { Component, ElementRef, NgZone, Renderer2 } from '@angular/core';
518+
import { ComponentFixture, async } from '@angular/core/testing';
519+
import { StackLayout } from '@nativescript/core';
520+
import {
521+
nsTestBedAfterEach,
522+
nsTestBedBeforeEach,
523+
nsTestBedRender
524+
} from 'nativescript-angular/testing';
525+
526+
@Component({
527+
template: `
528+
<StackLayout><Label text="Layout"></Label></StackLayout>
529+
`
530+
})
531+
export class ZonedRenderer {
532+
constructor(public elementRef: ElementRef, public renderer: Renderer2) {}
533+
}
534+
535+
describe('Renderer E2E', () => {
536+
beforeEach(nsTestBedBeforeEach([ZonedRenderer]));
537+
afterEach(nsTestBedAfterEach(false));
538+
afterAll(() => {});
539+
540+
it('executes events inside NgZone when listen is called outside NgZone', async(() => {
541+
const eventName = 'someEvent';
542+
const view = new StackLayout();
543+
const eventArg = { eventName, object: view };
544+
const callback = arg => {
545+
expect(arg).toEqual(eventArg);
546+
expect(NgZone.isInAngularZone()).toBeTruthy();
547+
};
548+
nsTestBedRender(ZonedRenderer).then(
549+
(fixture: ComponentFixture<ZonedRenderer>) => {
550+
fixture.ngZone.runOutsideAngular(() => {
551+
fixture.componentInstance.renderer.listen(
552+
view,
553+
eventName,
554+
callback
555+
);
556+
557+
view.notify(eventArg);
558+
});
559+
}
560+
);
561+
}));
562+
});
563+
564+
```
565+
566+
### Run Your Tests
567+
568+
After you have completed your test suite, you can run it on physical devices or in the native emulators.
569+
570+
#### Requirements
571+
572+
Before running your tests, verify that your development machine and your testing devices meet the following prerequisites.
573+
574+
- The Android native emulators on which you want to run your tests must be running on your development machine. To verify that your machine recognizes the devices, run the following command.
575+
576+
```Shell
577+
ns device
578+
```
579+
580+
- The physical devices on which you want to run your tests must be connected to your development machine. To verify that your machine recognizes the devices, run the following command.
581+
582+
```Shell
583+
ns device
584+
```
585+
586+
- The physical devices on which you want to run your tests must be able to resolve the IP of your development machine. To verify that the device can access the Karma server, connect the device and the development machine to the same Wi-Fi network or establish USB or Bluetooth tethering between the device and the development machine.
587+
- Port 9876 must be allowed on your development machine. The Karma server uses this port to communicate with the testing device.
588+
589+
#### Run the Tests
590+
591+
To execute your test suite on any connected Android devices or running Android emulators, run the following command.
592+
593+
```Shell
594+
ns test android
595+
```
596+
597+
To execute your test suite on connected iOS devices, run the following command.
598+
599+
```Shell
600+
ns test ios
601+
```
602+
603+
To execute your test suite in the iOS Simulator, run the following command.
604+
605+
```Shell
606+
ns test ios --emulator
607+
```
608+
609+
To execute your test suite in CI make sure to add `--justlaunch`. This parameter will exit the simulator.
610+
611+
```Shell
612+
ns test ios --emulator --justlaunch
613+
```
614+
615+
Each execution of `$ ns test` consists of the following steps, performed automatically.
616+
617+
1. The CLI starts a Karma server on the development machine.
618+
1. The CLI prepares, builds and deploys your project, if not already deployed. If already deployed, the CLI synchronizes changes to the application package.
619+
1. The CLI embeds the NativeScript unit test runner and your host network and Karma configuration in the deployed package.
620+
1. The CLI launches the main module of the NativeScript unit test runner instead of launching the main module of your app.
621+
1. The NativeScript unit test runner uses the embedded network configuration to try to connect to the Karma server on the development machine.
622+
1. When the connection between the NativeScript unit test runner and the Karma server is established, the test runner begins the execution of the unit tests.
623+
1. When the execution completes, the NativeScript unit test runner reports the results to the Karma server.
624+
1. The Karma server reports the results on the command line.
625+
626+
#### Re-Run Tests on Code Change
627+
628+
The NativeScript can continuously monitor your code for changes and when such changes occur, it can deploy those changes to your testing devices and re-run your tests.
629+
630+
To enable this behavior, run your `$ ns test` command with the `--watch` flag. For example:
631+
632+
```Shell
633+
ns test android --watch
634+
ns test ios --watch
635+
ns test ios --emulator --watch
636+
```
637+
638+
The NativeScript CLI remains active and re-runs tests on code change. To unlock the console, press `Ctrl+C` to stop the process.
639+
640+
#### Configure the Karma Server
641+
642+
When you configure your project for unit testing, the NativeScript CLI adds `karma.conf.js` to the root of your project. This file contains the default configuration of the Karma server, including default port and selected testing framework. You can edit this file to customize your Karma server.
643+
644+
When you modify `karma.conf.js`, make sure that your changes meet the specification of the [Karma Configuration File](http://karma-runner.github.io/1.0/intro/configuration.html).
645+
646+
### Continuous Integration
647+
648+
To integrate the NativeScript unit test runner into a continuous integration process, you need to configure a Karma reporter, for example, the [JUnit reporter](https://github.com/karma-runner/karma-junit-reporter).
649+
360650
## Using packages
361651
362652
## Updating
@@ -383,7 +673,7 @@ If you do choose to [try Visual Studio Code](https://code.visualstudio.com/), le
383673
384674
After you install Visual Studio Code, you can open projects using the editor’s `File` → `Open` menu option, but there’s an alternative option that works far better for command-line-based projects like NativeScript: the `code` command.
385675
386-
The `code` command runs in your command-line or terminal, and it works just like the `tns` command does for NativeScript apps. Visual Studio Code installs the `code` command by default on Windows on Linux, but on macOS, there’s [one manual step](https://code.visualstudio.com/docs/setup/mac) you must perform.
676+
The `code` command runs in your command-line or terminal, and it works just like the `ns` command does for NativeScript apps. Visual Studio Code installs the `code` command by default on Windows on Linux, but on macOS, there’s [one manual step](https://code.visualstudio.com/docs/setup/mac) you must perform.
387677
388678
Once set up, you can type `code .` in your terminal to open the files in your current folder for editing. For example, you could use the following sequence of command to create a new NativeScript app and open it for editing.
389679

0 commit comments

Comments
 (0)