aVolpe Blog

[WIP] Applying the Tester Pattern in React Testing

Fri, 31 Jan 2025 00:00:00 +0000

The tester pattern is a great way to structure your tests to improve readability and making it easier to write and expand the test suite.

In the original webpage, the author explains the concepts in Java, in this blog we will apply the pattern in JavaScript, specifically in a React SPA.

The libraries that we will be using are:

vitest as the runner and mock library
React testing library to interact with React components.

Let’s explore the pattern with examples of increasing complexity:

a simple component that draws a static message
a form with various inputs.
the same component, but the message is a quote from a web service. Using MSW for the test.

first scenario: simple component

Let’s test this component:

export const HelloWorld = (props) => (
    <div>
        Hello {props.name}
    </div>
)

To test the rendering of this component, we can write a simple test:

describe('simpleComponent', () => {
    it('renderAndUpdateGreeting', async () => {
        const tester = new HelloWorldPageTester()
                           .withName('Arturo');
        
        let asserter = await tester.whenRender();
        await asserter.hasText("Hello Arturo");

        tester.withName('Volpe');
        asserter = await tester.whenRerender();
        await asserter.hasText("Hello Volpe");
    });
});

For this simple case, adding tester and asserter helper classes may seem like overkill. However, an interesting side effect is that the test does not rely on any component-specific selectors

The test is in ‘plain’ English (with the limitation of the language) and the helper classes can be user for multiple tests.

The tester and asserted used:

class HelloWorldPageTester {

    name: String = "";
    component!: RenderResult;

    withName(name: string) { this.name = name; return this; }

    whenRender() {
        this.component = render(<HelloWorld name={this.name} />);
        return new HelloWorldPageAsserter(this.component);
    }

    whenRerender() {
        this.component.rerender(<HelloWorld name={this.name} />);
        return new HelloWorldPageAsserter(this.component);
    }
}

class HelloWorldPageAsserter {
    constructor(private component: RenderResult) {}

    async hasText(expectedText: string) {
        await this.component.findByText(expectedText);
        return this;
    }
}

Links:

Component: HelloWorld.tsx
Test: HelloWorld.test.tsx

A note about async/await

Ideally we want a fluent syntax when using the tester pattern, for example in Java we can have a bunch of asserts chained:

new BookTester()
    .givenAuthor("Arturo Volpe")
    .givenHasChapter("1 - VITE")
    .givenHasChapter("2 - The pattern")
    .whenPublish() // return asserter
    .thenHasInCover("Author: Arturo Volpe")
    .thenHasInChapters(2);

To map this to a react-testing-library test, we need to use async/await, normally the asserter methods are required to be async in order to use the findBy methods, so we need to migrate to:

const tester = new BookComponentTester()
                    .givenAuthor("Arturo Volpe")
                    .givenHasChapter("1 - VITE")
                    .givenHasChapter("2 - The pattern");

// normally here we render/fill the 'page'
const asserter = await tester.whenRender();

await asserter.thenHasInCover("Author: Arturo Volpe");
await asserter.thenHasInChapters(2);

If the pipeline operator added to the language, this syntax could become more concise:

new BookComponentTester()
   .givenAuthor("Arturo Volpe")
   .givenHasChapter("1 - VITE")
   .givenHasChapter("2 - The pattern")
   // normally here we render/fill the 'page'
   |> await %.whenRender()
   |> await %.thenHasInCover("Author: Arturo Volpe")
   |> await %.thenHasInChapters(2)

Second scenario: A simple form

The Tester Pattern really shines when testing multiple use cases that share a similar setup but require specific assertions. In this case, we will test a form for editing personal information (first name and last name).

For the form we will use react-hook-form, and the getting started page form with some small modifications.

In this form, we have two inputs:

name: the first name, required, max length 10
last name: the last name, not required, max length 20

type Inputs = {
  lastname: string
  firstname: string
}

export function Step2Form(props: {
    onSubmit: (dat: Inputs) => void
}) {
  const {
    register,
    handleSubmit,
    watch,
    formState: { errors },
  } = useForm<Inputs>()
    const onSubmit: SubmitHandler<Inputs> = (data) => props.onSubmit(data); 

    return <form onSubmit={handleSubmit(onSubmit)}>

        <input {...register("firstname", { required: true, maxLength: 10 })} 
               data-testid="firstname-input"/>
        {errors.firstname 
            ? <span>This field is invalid</span>
            : <span>The firstname is valid</span>}

        <input {...register("lastname", { maxLength: 20 })} 
               data-testid="lastname-input"/>

        <span>The form has {Object.keys(errors).length} errors</span>
        <input type="submit" data-testid="step2-button" value="Save" />
    </form>

}

Some spans are added to make the test easier to write, in the real world, those messages may appear under the inputs or in other parts of the form, the data-testid may be replaced with findByRole, etc.

Ideally we want very descriptive tests for this form, an easy way to write all the different cases, required fields, invalid lengths, etc, lets start with a simple test that check that the ‘happy path’ works:

describe('step2Form', () => {
    it('renderValidValues', async () => {
        const tester = new Step2FormPageTester()
            .withName('Arturo')
            .withLastname('Volpe');
        
        let asserter = await tester.whenDoSubmit();
        await asserter.hasAllFieldsValid();
    });
});

In this test we create a tester that populates both fields and clicks the button, in this case the tester is like a robot, we give the tester some instructions, and the tester execute the required steps.

Reading this test we don’t know anything about the internals of the component, we only know that we are asking the tester to submit the form with a given name and last name. The internals of the component and the complexity of the emulation of user actions is hidden to the test, making it easy to read and follow.

The tester for this form is slightly more complex:

class Step2FormPageTester {

    name: String = "";
    lastname: String = "";
    component!: RenderResult;

    withName(name: string) { this.name = name; return this; }
    withLastname(lastname: string) { this.lastname = lastname; return this; }

    async whenDoSubmit() {
        this.component = render(<Step2Form onSubmit={this.submitCallback} />);

        await this.fillInput("firstname-input", this.name);
        await this.fillInput("lastname-input", this.lastname);

        return new Step2FormPageAsserter(this.component, this.submitCallback);
    }

    async fillInput(targetTestId: string, toInsert: string) {
        const input = await this.component.findByTestId(targetTestId);
        fireEvent.change(input, {target: {value: toInsert}})
        return this;
    }

}

class Step2FormPageAsserter {
    constructor(private component: RenderResult,
                private callback: (dat: Inputs) => void) {}

    async hasText(expectedText: string) {
        await this.component.findByText(expectedText);
        return this;
    }

    async hasAllFieldsValid() {
        return this.hasText('The form has 0 errors');
    }
}

The Tester encapsulates some ‘component knowledge’—it knows how to find the required inputs. This logic can be complex, especially when testing frontend components. Sometimes, we need to wait for rendering; other times, we must use a complex CSS selector. However, all of this is hidden as an implementation detail within the Tester.

A note about the Tester for React Components

We can use the Page Object Model popularized by tools like selenium or playwright to create the tester. This is more similar to what a user would do when using the component.

In the original tester pattern, we are testing a action, like calling an endpoint or a method, but now we are testing the user actions, so it’s better to test a sequence of actions, in this example the filling of a form.

Using this pattern we can have another approach, instead of giving the Tester all the information that it need to perform the action, we instruct it like a robot:

describe('step2Form', () => {
    it('renderValidValuesRobot', async () => {

        const tester = new Step2FormPageRobotTester();

        await tester.givenComponentRendered();
        await tester.givenFirstname('Arturo');
        await tester.givenLastname('Volpe');
        
        let asserter = await tester.whenDoSubmit();
        await asserter.hasAllFieldsValid();
    });
    
    it('firstName.inmediateFeedback', async () => {

        const tester = new Step2FormPageRobotTester();

        await tester.givenComponentRendered();
        let asserter = await tester.whenFirstnameFilled('');
        
        await asserter.hasMessage('Firstname is required');
    });
});

class Step2FormPageRobotTester {

    component!: RenderResult;

    givenComponentRendered() { 
      this.component = render(<Step2Form />); 
    }
    givenFirstname(targetName: string) { 
      return this.fillInput("firstname-input", targetName); 
    }
    givenLastname(targetName: string) { 
      return this.fillInput("lastname-input", targetName); 
    }

    async whenDoSubmit() {
        const bttn = await this.component.findByText('Save');
        fireEvent.click(bttn);
        return new Step2FormPageAsserter(this.component);
    }

    async fillInput(targetTestId: string, toInsert: string) {
        const input = await this.component.findByTestId(targetTestId);
        fireEvent.change(input, {target: {value: toInsert}})
        return this;
    }
    
    async whenFirstnameFilled(targetName: string) { 
      await this.fillInput("firstname-input", targetName); 
      return new Step2FormPageAsserter(this.component);
    }
}

Adding more tests cases

Once we write the tester, adding more scenarios is trivial:

    it('validateEmptyFields', async () => {
        const tester = new Step2FormPageTester()
            .withName('')
            .withLastname('');
        
        let asserter = await tester.whenDoSubmit();
        await asserter.hasInvalidFieldsCount(1); // only the name is required
        await asserter.hasInvalidFirstName();
    });

    it('validateInvalidFields', async () => {
        const tester = new Step2FormPageTester()
            .withName('super large name that exceed the expected length')
            .withLastname('super large lastname that exceed the expected length');
        
        let asserter = await tester.whenDoSubmit();
        await asserter.hasInvalidFieldsCount(2);
        await asserter.hasInvalidFirstName();
    });

Adding two new tests only required two new assertions:

// FormAsserter
    async hasInvalidFieldsCount(expectedCount: number) {
        return this.hasText(`The form has ${expectedCount} errors`);
    }

    async hasInvalidFirstName() {
        return this.hasText(`This field is invalid`);
    }

Using the tester pattern, adding more tests is easy once we have the tester and the asserter with many features.

An extra complexity, verifying the invocation to the callback

The Step2Form component receives a callback as a property, this callback is invoked only when the form is valid, the first argument of the function is the valid object.

To verify that the function is only called when we have a valid form, we need to mock a call, lets do that in the Tester:

class Step2FormPageTester {

    // ...
    submitCallback: (dat: Inputs) => void = vi.fn();
    // ...

    async whenDoSubmit() {
        // .. same as before

        const bttn = await this.component
                .findByText('Save');

        fireEvent.click(bttn);

        return new Step2FormPageAsserter(this.component, this.submitCallback);
    }

Here we can have two different asserts, one to check for contents in the page, and another one to assert the invocations to the function. For simplicity, we will only use one.

With this mock (vn.fn()) function, we can add assertions:

class Step2FormPageAsserter {
    constructor(private component: RenderResult,
                private callback: (dat: Inputs) => void) {}

    // ...

    async callbackWasNotCalled() {
        expect(this.callback).toHaveBeenCalledTimes(0);
        return this;
    }

    async callbackWasCalledWith(expected: Inputs) {
        expect(this.callback).toHaveBeenCalledWith(expected);
        return this;
    }
}

And modify the tests:

    it('renderValidValues', async () => {
        const tester = new Step2FormPageTester()
            .withName('Arturo')
            .withLastname('Volpe');
        
        let asserter = await tester.whenDoSubmit();
        await asserter.hasAllFieldsValid();
        await asserter.callbackWasCalledWith({
            firstname: 'Arturo',
            lastname: 'Volpe'
        });
    });
    it('validateEmptyFields', async () => {
        const tester = new Step2FormPageTester()
            .withName('')
            .withLastname('');
        
        let asserter = await tester.whenDoSubmit();
        await asserter.hasInvalidFieldsCount(1);
        await asserter.hasInvalidFirstName();
        await asserter.callbackWasNotCalled();
    });

Links:

Component: Step2Form.tsx
Test: Step2Form.test.tsx

All the source code for the examples is in the vitest pattern playground github repo

Alternatives for handling uncaugh exception in javascript api clients

Tue, 11 Dec 2018 00:00:00 +0000

Modern javascript http clients use promises or somethings similar (for this post, angular Observables are similar enough, so this post also is relevant to angular), and a common issue with this approach is that sometimes we want to show a default message to the user when something went wrong

I am using the fetch standard API in this blog, but the same can be achieve with similar libraries like the browser axios or the default angular http client.

Let imagine we need to access a rest API, so we create a simple class to handle all the logic and interactions with this API, like this:

export class APICaller {

  constructor() {
  }

  handleError(response) {
    if (response.status >= 200 && response.status < 300)
      return response;
    const error = new Error(response.statusText);
    error.response = response;
    throw error;
  };

  doGet (url) {
    return fetch(url)
      .then(response => this.handleError(response))
      .then(okResponse => okResponse.json())
  };

  getTodoList() {
    return this.doGet(`https://jsonplaceholder.typicode.com/todos/`)
  }
  getTodo(todoId) {
    return this.doGet(`https://jsonplaceholder.typicode.com/todos/${todoId}`)
  }

}

This example uses the excellent (and free) json placeholder example API to handle a list of todos.

With this class, we can get the list using:

const api = new APICaller();
api.getTodoList()
    .then(list => console.log(list));

This will print all the todos, if we want to handler the errors, we can simply add a catch clause:

const api = new APICaller();
api.getTodoList()
    .then(list => console.log(list))
    .catch(err => console.log('fail to load todos', err))

This is fairy easy and common in many modern web apps, but the problem is when we want to add a global error handler.

Let’s suppose the server is down, we can check this like this:

const api = new APICaller();
api.getTodoList()
  .then(list => console.log(list))
  .catch(err => {
    if (err.message === 'Failed to fetch') {
      console.log('the server is down');
   } else {
      console.log('unkknown error');
   }
})

This will work, but the problem is that the we don’t want to check in every call if the server is down, and also this will provoke that we will have duplicated code everywhere, now we will see some options.

First attempt, global handler in the `APICaller`

What if we check for this kind of errors in the APICaller class?, lets change our handleError method, like this:

  handleError(response) {
    if (response.status >= 200 && response.status < 300)
      return response;
    if (response.statusText === 'Failed to fetch') {
      console.log('the server is down');
    }
    const error = new Error(response.statusText);
    error.response = response;
    throw error;
  };
}

In this case we can remove the catch, and all the exception will be correctly handled in our method, we can try to extend this will every other statusText message.

  handleError(response) {
    if (response.status >= 200 && response.status < 300)
      return response;
    switch(response.statusText) {
    case 'Failed to fetch':
      console.log('the server is down');
      break;
    case 'Unauthorized':
      console.log('you need to log in first');
      break;
    default:
      console.log('Server error');
      break;
    }

    const error = new Error(response.statusText);
    error.response = response;
    throw error;
  };

But what happens if we want to handle some exceptions in our code, and all the others in the global handler?

Well this will not work, because if we try something like this:

new APICaller().getTodoList()
  .then(list => console.log(list))
  .catch(err => {
    console.log('personalized message');
  })

The console will print two messages, first the global one and then the personalized message, this is because the order of execution is like this:

First is executed the fetch
If there is an error the global handler is called
Finally the custom catch is invoked

We can’t change the behaviour of the second step we we are in the third, but, we have some options!

First approach, parameter in the call

We can change the method getTodoList so it accept and argument, and object with options to our APICaller, for example, we can do this:

  handleError(response, showError) {
    if (response.status >= 200 && response.status < 300)
      return response;

    if (showError) { /* here the switch */ }
    const error = new Error(response.statusText);
    error.response = response;
    throw error;
  };

  doGet (url, options) {
    return fetch(url)
      .then(response => this.handleError(response, options.showError))
      .then(okResponse => okResponse.json())
  };

  getTodoList(options) {
    return this.doGet(`https://jsonplaceholder.typicode.com/todos/`, options)
  }

  // usage:

  new APICaller().getTodoList({ showError: false })
    .then(list => console.log(list))
    .catch(err => {
      console.log('personalized message');
    })

This will work, and if we pass the second parameter, the global message will not apear. The real issue with this approach is that we need to add an extra object to every single call.

Second approach, flag on the response

We can also use the fact that we can add arbitrary props to an exception, for example, we can add a flag to the error when we catch it.

For this approach to work, we need to change the order of the execution, to this:

First is executed the fetch
The custom catch is invoked
The global handler is executed

We can implement this approach fairy easy with the help the setTimeout method, like this:

  handleError(response) {
    if (response.status >= 200 && response.status < 300)
      return response;

    const error = new Error(response.statusText);
    error.response = response;

    setTimeout(() => {
       if (!error.handled) { /* here the switch */ }
    }, 100)
    
    throw error;
  };

  ... The rest unchanged

  // usage:

  new APICaller().getTodoList()
    .then(list => console.log(list))
    .catch(err => {
      err.handled = true;
      console.log('personalized message');
    })

This will work, and we have total control about the global error message, the issue it’s that we need to change every single catch to touch that flag.

Another advantage of this method is that we can do some code completely unrelated to the exception in the catch (cleanup for example) and if we don’t assign the flag the global error will be created.

If we forget that the global error message exists and don’t set the flag, the worst case scenario is that an extra message will be displayed.

This is my preferred way of handling this problem.

Third approach, magic with proxies

If we don’t like the flag, we can use another approach to show global messages only if the user don’t catch it, we can use javascript proxies.

The mozilla documentation defines a proxy as:

The Proxy object is used to define custom behavior for fundamental 
operations (e.g. property lookup, assignment, enumeration, function 
invocation, etc).

We can use this object to intercept usages of our exception and show the global message only if the programmer don’t use our exception, like this:

  // APICaller.js

  buildProxyException(data) {
    let handled = false;
    const handler = {
      get: (obj, prop) => {
        handled = true;
        return data[prop];
      }
    };

    setTimeout(() => {
      if (!handled) {
        /* here the big switch */
      }
    }, 100);

    const proxy = new Proxy(data, handler);
    proxy.original = data;
    return proxy;
  };


  handleError(response) {
    if (response.status >= 200 && response.status < 300)
      return response;

    const error = new Error(response.statusText);
    error.response = response;

    throw this.buildProxyException(response);
  };

  ... The rest unchanged

  // usage without global error:

  new APICaller().getTodoList()
    .then(list => console.log(list))
    .catch(err => {
      if (err.code === 'MY_CUSTOM_CODE')
         console.log('personalized message');
    })

  // usage with global error:

  new APICaller().getTodoList()
    .then(list => console.log(list))

In this example, the console.log only will be executed if we use an property of the error (in the example err.code).

This is the most magical approach, the only issue is that we can’t not longer let the global handler manage the error once we use the Exception.

What do you think? How do you handle the global messages?

Test your components in Ionic 4

Fri, 07 Dec 2018 00:00:00 +0000

Ionic 4 is the next version of the Ionic framework, currently is in beta, but it works well, one of the major differences between this release and the previous is the dependency with Angular.

In Ionic 4 Angular is provided as an option (currently with Vue) and when you use the Ionic cli, all the commands use ‘angular-cli’ in the backgrounds and make little modifications to the code they generate.

In this post I will show you how to make a simple test that mocks the user interaction with a form and how to setup and execute all tests.

First, we start creating a simple new project

npm install -g ionic
ionic start simpleProject tabas

When the cli ask if we want to use Ionic 4 press ‘y’.

This project already has some test, but they are very basic, if we want to try our pages with Ionic components, we need some modifications first.

First, run the test

To run the unit test, we simple run:

npm run test

And a chrome window will apear and it will run all tests, you will se something like this in your console:

...
INFO [Chrome 70.0.3538 (Mac OS X)]: Connected on socket 4v72_3NckUMqwCHLAAAA with id 67941402
Chrome 70.0.3538 (Mac OS X 10.14.1): Executed 6 of 6 SUCCESS (0.22 secs / 0.198 secs)
TOTAL: 6 SUCCESS
TOTAL: 6 SUCCESS

Everything works fine out of the box.

Second, add some ionic components

In the component tab1.page.ts we will add an input text and a button, when we press the button, a Alert will show saying hello ${name}

// tab1.page.ts
import {Component} from '@angular/core';
import {AlertController} from '@ionic/angular';

@Component({
    selector: 'app-tab1',
    templateUrl: 'tab1.page.html',
    styleUrls: ['tab1.page.scss']
})
export class Tab1Page {
    public name: string;

    constructor(public alertController: AlertController) {
    }

    async sayHello() {
        const alert = await this.alertController.create({
            header: 'Test',
            subHeader: `Hola ${this.name}`
        });
        await alert.present();
    }
}

<!-- tab1.page.html -->
<ion-content>
    <ion-list>
        <ion-item>
            <ion-input [(ngModel)]="name" id="name" placeholder="Hola"></ion-input>
        </ion-item>
        <ion-item>
            <ion-button (click)="sayHello()">Click</ion-button>
        </ion-item>

    </ion-list>
</ion-content>

This is a very simple component, we insert some text, and press the button and an alert apear.

Third, the test

If we run our test, we will see that there is one failing, the test of the tab1.page.ts, this is because we don’t provide a AlertController provider, and angular can’t perform the dependency injection in our component.

We can fix this in our TestBed configuration, simple add:

    //  tab1.page.spec.ts
    beforeEach(async(() => {
        TestBed.configureTestingModule({
            declarations: [Tab1Page],
            schemas: [CUSTOM_ELEMENTS_SCHEMA],
            providers: [{
                provide: AlertController, useValue: null
            }]
        }).compileComponents();
    }));

If we check our test output, it will say now that all test are passing, now we can make real tests.

Let’s make a simple test that ensure that every change to our input is reflected on our component.

We will use a little helper from the angular test suite called fakeAsync, this helper should wrap the entire test, and it provides a simple function tick() to simulate time.

    //  tab1.page.spec.ts
    it('should update value', fakeAsync(() => {
        const userInput: Input = fixture.nativeElement.querySelector('#name');

        userInput.value = 'html.userName';

        tick(1000);

        expect(component.name).toBe('html.userName');
    }));

This is a simple test, first we search for the ion-input, we update the value, and then check if the component has the same value, it’s simple enough, too bad it doesn’t work.

To be able to test Ionic components, we need to add the IonicModule and another dependencies, we change the test to be like this:

    //  tab1.page.spec.ts
    beforeEach(async(() => {
        TestBed.configureTestingModule({
            declarations: [Tab1Page],
            schemas: [CUSTOM_ELEMENTS_SCHEMA],
            imports: [
                FormsModule,
                CommonModule,
                BrowserModule,
                IonicModule.forRoot({
                    _testing: true
                }),
            ],

            providers: [
                {provide: AlertController, useValue: null},
                {provide: NavController, useValue: null}
            ]
        }).compileComponents();
    }));

    beforeEach(async () => {
        fixture = TestBed.createComponent(Tab1Page);
        component = fixture.componentInstance;
        fixture.detectChanges();
        await fixture.whenRenderingDone();
        await fixture.whenStable();
    });

    //  tab1.page.spec.ts
    ...
            providers: [
                {provide: AlertController, useValue: new MockAlertController()},
                {provide: NavController, useValue: null}
            ]

   ...

In the first beforeEach we add some modules that are used in our code to make the [(ngModel)] works, we add the IonicModule, and, because in some part the navController is injected in that module, we need to provide a value for that controller.

In the second beforeEach we change the code to wait for ionic to load all the components, and only proceed when everything is stable.

If we check now our test console, everything should be fine.

Now it’s time to test the alert, to do this I will provide you with a simple MockAlertController class that will help us in our testing process, you can get it here ionicMocks, with this, we can simply add to our test:

    //  tab1.page.spec.ts
    ...
        component.sayHello();


        tick(1000);

        const mockAlertController = component.alertController as any as MockAlertController;

        expect(mockAlertController.getLast().visible).toBeTruthy();
        expect(mockAlertController.getLast().header).toBe('Test');
        expect(mockAlertController.getLast().subHeader).toBe('Hola html.userName');

This works great! Let me know if you have an issue!.

Metric collection using ionic and fabric

Mon, 26 Feb 2018 00:00:00 +0000

Fabric

Fabric is a group of tools that are very useful for various common task in an typical mobile app development, in this blog we will explore various parts of fabric including Crashlytics, Beta and Answers.

First you need to create an account and a organization (various apps are grouped in an organization), and then go to Organizations page, you need to copy the API key and the Build Secret to install all the tools and plugins that we will cover.

Cordova plugin

The fabric plugin by Sarriaroman is a very useful and easy to use plugin that will allow the integration of the fabric tools.

ionic cordova plugin add cordova-fabric-plugin \
               --variable FABRIC_API_KEY=$API_KEY \
               --variable FABRIC_API_SECRET=$BUILD_SECRET

For the official installation process go to plugin installation page

Note: This plugins works only in a mobile device, when you are using the browser to test the app the plugin will not be available.

Note: You will have one ‘aplication’ per platform, this means that you don’t need to identify any of your request because the data for every platform will be stored and handled independently.

Ionic integration

If you are using Ionic 2, 3 or later, then maybe you want TypeScript integration, to achieve this, you need to add to your tsconfig.json the following:

  ...
  "files": [
    "plugins/cordova-fabric-plugin/typings/cordova-fabric-plugin.d.ts"
  ],
  ...

Note: For an example of how to use this typings you can go to the typings examples.

Crashlytics

Crashlytics is a very useful tool to report crash and other events (like not fatal crashes and errors).

if (window['fabric']) {
   fabric.Crashlytics.sendNonFatalCrash(message);
}

The first check is to prevent to use the plugin in the browser.

Store user data

To add metadata to your reports you need to use various specific methods to store the info, the main method is setXXXValueForKey (XXXX can be String, Int, Bool or Float), but there are other specific methods to store user data:

setUserName
setUserEmail
setUserIdentifier

When the user login you can store this data, and when the user log outs we need to set the values of this keys to null.

Answers

In a similar way, we can use the tool Answers, which is a tool to store various events and to keep a track of actions of the user, for example we can track successful logins, track a shopping cart, start of game levels, etc (you can create your custom events too).

You can create a simple AnswerProvider to abstract the plugin and has an single access point to Answers

First, let create the provider:

ionic g provider answer

And edit the constructor (we don’t need the HttpClient that comes by default with every provider):

constructor(public platform: Platform) {

    platform.ready().then(
        () => {
            if (window['fabric'])
                this.answers = fabric.Answers;
            else
                this.answers = null;
        }
    )

}

And then add methods for our usage, for example to store and payment event:

public endPurchase(item: string, 
                  itemType: string, 
                  itemId: string, 
                  currency = 'USD', 
                  success = true, 
                  amount = 0) {
    if (!this.answers) return;
    this.answers.sendPurchase(amount, currency, success, item, itemType, itemId);

}

Note: The if(!this.answers) must be in every single method of this provider, and you can accept your objects and handle the logic to translate your events and the types of events in Answers

I will update this blog with more information about the various tools, including beta and firebase

Dropwizard Metrics with JaxRS

Fri, 19 May 2017 00:00:00 +0000

Dropwizard Metrics is a Java library that provides tools to measure an application.

Dropwizard offer various tools that help you with distinct metrics, like gauges, counters, histograms and other.

The library has two phases, the first is the recollection of data and the second is the reporting of the collected data to a data collector, in this post we will integrate the recollection of data to an existing standard Java EE application.

First we need to create a MetricRegistry instance that will allows us to create the various objects than implement the metric recollection, this registry can be stored in a Application Bean if you are using CDI, or in an Singleton bean if you are using only EJB.

This class can look like:

@ApplicationScoped
public class Registry {

    private MetricRegistry metricRegistry;

    @PostConstruct
    public void init() {

        metricRegistry = new MetricRegistry();

        configureListeners();
    }

    public Counter counter(Class<?> clazz, String resource) {
        return metricRegistry.counter(MetricRegistry.name(clazz, resource));
    }

    public Timer timer(Class<?> clazz, String resource) {
        return metricRegistry.timer(MetricRegistry.name(clazz, resource));
    }

    private void configureListeners() {
        // in this part we can configure the data recollection tools, like        
        // the ConsoleReporter or the GraphiteReporter
    }

In this example we provide only two collectors, you can implement the others in a similar way.

Simple usage

Now, we can use this bean, suppose we has a redis connection managed by Jedis, Jedis provides us with a class called JedisPool that is a pool of jedis instances.

This pool can have multiple jedis instances inside, and we are interested in the number of instances that are used, and how many instances are available at any moment, for this we can use metrics.

So we create a class that has a @Produces the jedis instances, something like this:

@ApplicationScoped
public class JedisProvider {

    @Inject
    private MetricRegistry metricRegistry;

    /**
     * Our pool
     */
    private JedisPool jedisPool;

    /**
     * Our metrics counter
     */
    private Counter counter;

    @PostConstruct
    public void init() {

        JedisPoolConfig jedisConfig = new JedisPoolConfig();
        jedisPool = new JedisPool(jedisConfig, "localhost", "5432");

        counter = registry.counter(getClass(), "redis");
    }

    @Produces
    public Jedis build() {
        counter.inc();
        return provider.getResource();
    }
    
    public void close(@Disposes Jedis jedis) {
        counter.dec();
        jedis.close();
    }

With this, every time a new @Inject Jedis jedis is processed, the counter will increase, and after the bean has been used, the counter will decrement.

For this example we can also use gauges.

Using JaxRS request and response filters

Metrics provide a interesting measure, the Timer. This measure has a annotation called @Timed, unfortunately I was unable to find any implementation that works will JaxRS (and Resteasy, there is an Jersey implementation, but use custom Jersey function and classes).

We can create our custom @Timed annotation, and annotate it with @NameBinding, so we can use it as a binding annotation and is available to us in the JaxRS filters.

The annotation looks like:

@NameBinding
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.TYPE, ElementType.METHOD })
public @interface Timed {
}

And we can implement a simple JaxRS filter like this:

@Provider
@Priority(Priorities.USER)
@Timed
public class MetricsFilter implements ContainerRequestFilter, ContainerResponseFilter {

    @Context
    private ResourceInfo resourceInfo;

    @Inject
    private Registry registry;

    @Inject
    private HttpServletRequest servletRequest;


    @Override
    public void filter(ContainerRequestContext requestContext) throws IOException {

        Timer timer = registry.timer(
            resourceInfo.getResourceClass(), 
            resourceInfo.getResourceMethod().getName());
        Timer.Context counter = timer.time();
        servletRequest.setAttribute("timer.context", counter);
    }

    @Override
    public void filter(
             ContainerRequestContext requestContext, 
             ContainerResponseContext responseContext) 
        throws IOException {

        Timer.Context tc = (Timer.Context) servletRequest.getAttribute("timer.context");
        if (tc != null) {
            tc.stop();
            servletRequest.removeAttribute("timer.context");
        }

    }
}

This will intercept every petition to a class (or method) annotated with @Timed, and it will create a timer that will measure the duration of the request.

Important notes:

If we don’t use the @PreMatching annotation, this will be invoked after JaxRS find outs what method to invoke, so the time to find the correct method is not calculated.
This will not use any client side information, and only rely on the time that our methods take to execute
This will store the Context object in the servlet request, if we don’t want to populate our request, and later calculate the time.

We can use this like this:

    @Timed
    public Response authenticateUser(String email, String password, User.Type type) {
       // do important work
    }

Using Hibernate Spatial with Wildfly 9/10

Fri, 17 Jun 2016 00:00:00 +0000

Hibernate Spatial is a project that allows hiberante (and JPA) to use Spatial facilities provided by database vendor’s (like postgis).

If we are using a database provided datasource, we need to add the necessary dependencies to the hibernate module in Wildfly.

Dependencies

First we need hibernate spatial and all of its dependencies, by default, it’s depends on GeoLatte and VididSolutions JTS. Also, geolatte depends on slf4j.

To add this dependencies, we need to downloads the desired jars, for this guide, I will use Hibernate Spatial 5.0.7, JTS 1.13, and Geolatte 1.0.1, as Wildfly 10.0.0.Final currently ships with Hibernate 5.0.7, and JTS 1.13 and Geolatte 1.0.1 are transitive dependencies for Hibernate Spatial 5.0.7.

You can get the jars from:

You can also download the dependencies directly through the Maven CLI:

mvn dependency:copy -Dartifact=org.hibernate:hibernate-spatial:5.0.7.Final:jar -DoutputDirectory=.
mvn dependency:copy -Dartifact=org.geolatte:geolatte-geom:1.0.1:jar -DoutputDirectory=.
mvn dependency:copy -Dartifact=com.vividsolutions:jts:1.13:jar -DoutputDirectory=.

If you are using another version of Hibernate, you need to check the Hibernate pom.xml and use the correct versions.

Installation

Download the three jars to $JBOSS_PATH/modules/system/layers/base/org/hibernate/main, and modify the file module.xml that is in the same path.

In the <resources> tag, add:

<resource-root path="hibernate-spatial-5.0.7.Final.jar"/>
<resource-root path="jts-1.13.jar"/>
<resource-root path="geolatte-geom-1.0.1.jar"/>

And in the dependencies tag, add:

<module name="org.slf4j"/>

Also if you are using postgresql, you need to add in the dependencies tag:

<module name="org.postgresql"/>

And this is all.

Test

Add to your pom:

<dependency>
  <groupId>org.hibernate</groupId>
  <artifactId>hibernate-spatial</artifactId>
  <scope>provided</scope>
  <version>5.0.7.Final</version>
</dependency>

And create a entity like:

import javax.persistence.*;

import com.vividsolutions.jts.geom.Geometry;


@Entity
public class Place extends BaseEntity {

  @NotNull
  private Geometry location;

   // getters and setters
}

Now, we can create a query like:

SELECT
  distance(p.location, :userLocation)
FROM Place p
ORDER BY
  distance(p.location, :userLocation) ASC

And it will be translated to (if we are using postgresql) to:

SELECT st_distance(place0_.location, ?)
FROM place place0_
ORDER BY st_distance(place0_.location, ?)

Using Hibernate 5.2 with Wilfly 10 in Docker

Sun, 05 Jun 2016 00:00:00 +0000

The 1st of June Hibernate 5.2 was released, this release has some interesting features, like the consolidation of JPA in the core, and support for java 8 API’s.

Following the Hibernate official update guide, we need to replace the jars in the wildfly/modules folder.

In this blog, we will use the base docker image of Wildfly, with the tag 10.0.0.Final.

First, we create a simple Dockerfile:

FROM jboss/wildfly:10.0.0.Final
MAINTAINER Arturo Volpe <arturovolpe@gmail.com>

First, we need to get all the jars in the right place, the jars are available in Maven Central, so we add to our this

RUN cd $JBOSS_HOME/modules/system/layers/base/org/hibernate/main && \
    curl -O http://central.maven.org/maven2/org/hibernate/hibernate-core/5.2.0.Final/hibernate-core-5.2.0.Final.jar && \
    curl -O http://central.maven.org/maven2/org/hibernate/hibernate-envers/5.2.0.Final/hibernate-envers-5.2.0.Final.jar

RUN cd $JBOSS_HOME/modules/system/layers/base/org/hibernate/infinispan/main/ && \
    curl -O http://central.maven.org/maven2/org/hibernate/hibernate-infinispan/5.2.0.Final/hibernate-infinispan-5.2.0.Final.jar && \

This will download the 5.2 jars in the correct place (we need to replace hibernate-orm, envers, and infinispan).

The next step is remove the references and the jars of the previous release (for the base image, hibernate 5.0.7)

# Replace hibernate, hibernate-envers
RUN sed -i.bak "s/5.0.7/5.2.0/" module.xml && \
    sed -i.bak "/entitymanager/d" module.xml && \
    sed -i.bak "/java8/d" module.xml && \
    rm *.bak

# Replace infinispan
RUN rm *5.0.7.Final.jar && \
    sed -i.bak "s/5.0.7/5.2.0/" module.xml && \
    rm *.bak

And we are done, with this, hibernate by default must provide the 5.2.0.Final version of Hibernate.

To use this, we can do something like this:

@PersistenceContext
EntityManager em;

public Session getSession() {
    return em.unwrap(Session.class);
}

pgFouine with postgreSQL 9.4 in Docker

Mon, 11 Apr 2016 00:00:00 +0000

pgFouine is a log analyzer for PostgreSQL, it uses the postgreSQL log to create charts and statistics about the usage of a database, provides a useful visualization of the most expensive, common and heavy queries.

To configure pgfouine you need two things, change the log configuration of postgresql and has a working syslog log. Unfortunately the default image for postgreSQL has a data volume pointing to the /var/lib/postgresql directory, and the default configuration file is in /var/lib/postgresql/data/postgresql.conf. Everything after a VOLUME command is override at runtime, so you can’t not change the default file in the build process, this means that a simple Dockerfile is not enough.

In the source repo, the issues #105, and the merge #127 allows a user to expand the configuration through the .sample file, this can be a good option, in this entry we use another way, changing the only postgrseql configuration file, and configuring a full rsyslog.

First we need a working postgresql configuration file, for example we can get one from a container

 docker cp HASH:/var/lib/postgresql/data/postgresql.conf

Now, we need to configure postgres to log all to syslog:

Set the log method. Change #log_destination = 'stderr' to: log_destination = 'syslog'
Uncomment the following lines: syslog_facility = 'LOCAL0' syslog_ident = 'postgres'
Set the parameter log_min_duration_statement to 0 (to log all), this can be further tuned to log only the expensive queries.
Set the log_line_prefix to log_line_prefix = '%t [%p]: [%l-1] ', this is recommended by the pgFouine team.

This configuration is all that pgFouine needs from the postgreSQL log system, now, we need to use this configuration file in the postgreSQL instance, To allow us to change the configuration file, we need to get the docker-entrypoint.sh from the repo, and change it to copy the configuration file in every startup:

Add to your Dockerfile ADD postgresql.conf /postgresql.conf
When the scripts ask if the parameter is postgres (see this gist for more details):

echo 'Copying configuration file'
gosu root cp /postgresql.conf /var/lib/postgresql/data/postgresql.conf

With this, we have postgreSQL in a docker container configured to use rsyslog as the log facility. Now we need to install rsyslog, add the installation steps to the Dockerfile:

# to install rsyslog
RUN apt-get update && apt-get install -y rsyslog 
# to log all to /var/log/postgresql
RUN echo "local0.* -/var/log/postgresql/postgresql.log" > /etc/rsyslog.d/50-default.conf 
# to enable the rsyslog service*
RUN update-rc.d rsyslog enable

With the current configuration, postgreSQL floods the /var/log/messages and /var/log/syslog, to prevent this (this step is optional), we need to configure syslog to ignore the local0 (the configured facility) when logging to messages or syslog. To change the configuration file, we can go with sed and replace, or grab a working file for our container (if you execute docker at this moment, you will get a container with syslog, with a good default config file to grab), and modify the lines (the config file is in /etc/rsyslog.conf):

# In some part, in my case the line  62
*.*;auth,authpriv.none -/var/log/syslog
# In other part, in my case the line 94
mail,news.none -/var/log/messages

And replace with:

*.*;auth,authpriv.none,local0 -/var/log/syslog
local0,mail,news.none -/var/log/messages

Then, we add the configuration file to the proper location in our Dockerfile:

ADD ./rsyslog.conf /etc/rsyslog.conf

Now, you can run it!, to check if everything works fine, you can execute:

docker exec HASH tail -f /var/log/postgresql/postgresql.log

And see the log from the postgreSQL! (be careful, is very verbose).

P.D.: I has a problem with the syslog service, it will not start at the startup, so I change the docker-entrypoint.sh to start the service, see the final docker-entrypoint here.

This is my final Dockerfile:

FROM postgres:9.4 MAINTAINER Arturo Volpe <arturovolpe@gmail.com> ENV DB_NAME test ENV DB_USER admin ENV DB_PASS password RUN apt-get update && apt-get install -y wget && wget --no-check-certificate --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add - RUN sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt/ precise-pgdg main" >> /etc/apt/sources.list.d/postgresql.list' RUN apt-get update && apt-get install -y postgresql-9.3-postgis-2.1 -f ADD setup-database.sh /docker-entrypoint-initdb.d/ # this scripts creates a database, is optional RUN chmod 755 /docker-entrypoint-initdb.d/setup-database.sh # Instalar syslog RUN apt-get update && apt-get install -y rsyslog ADD ./rsyslog.conf /etc/rsyslog.conf RUN echo "local0.* -/var/log/postgresql/postgresql.log" > /etc/rsyslog.d/50-default.conf RUN update-rc.d rsyslog enable # Configuración de pgFouine ADD postgresql.conf /postgresql.conf # Ejecutable que inicia rsyslog y postgresql ADD docker-entrypoint.sh /docker-entrypoint.sh ENTRYPOINT [ "/docker-entrypoint.sh" ] CMD ["syslog", "postgres"]

The final files can be found in this gists.

Simple Atom reader with Ionic

Wed, 10 Feb 2016 00:00:00 +0000

Atom is a simple web feed format that handle the post data in XML, various CMS, and static site generators use it to allow third party software (like feedly) to notify it’s users when the site add more content.

The first problem to work with Atom and a JavaScript framework like Ionic, is that parse a XML is not as trivial as parse a Json File, to parse the XML you need some glue code.

The following snippet convert a ATOM Xml to a javascript object with some properties:

var parser = new DOMParser();
var xml = parser.parseFromString(xmlString, 'text/xml');

var entryData = xml.getElementsByTagName('entry');
var posts = [];

for (var i = 0; i < entryData.length; i++) {
  posts.push({
    id          : getFirstNode(entryData[i], 'id').innerHTML,
    title       : getFirstNode(entryData[i], 'title').innerHTML,
    content     : getFirstNode(entryData[i], 'content').innerHTML,
    image       : getImageLink(entryData[i], 'thumbnail', 'media')
  });
}

The trick is to use the DOMParser to parse the XML data, and then you can use it like any dom element (getDocumentById, getElementsByTagName, etc).

This snippet use two simple functions to extract the data from the Dom Element,

function getFirstNode(parent, nodeName, nameSpace) {
   if (!nameSpace)
      return parent.getElementsByTagName(nodeName)[0];
   return parent.getElementsByTagName(nodeName, nameSpace)[0];
}

function getImageLink(parent, nodeName, nameSpace) {
   var node = getFirstNode(parent, nodeName, nameSpace);
   if (node)
      return node.getAttribute('url');
   return null;
}

This example, produces a Json like this:

[
  {
    "id": "http://avolpe.github.io/ionic/2016/02/10/simple-atom-reader-with-ionic",
    "title": "Simple Atom reader with Ionic",
    "description": "Simple example of a rss feed reader with Ionic"
  }
]

About CORSS problems

If you debug with a browser instead of a real device (or emulator), and you use a external Atom XML file (for example, a Atom file from a wordpress blog), you will get a CORS exception (that means, the file author don’t allow third party webpages access their content) when you try to get the file. In a real device you don’t have this problem, because you are not a webpage.

To fix this issue, you need to create a Ionic Proxy, to achieve this, add something like this in your ionic.project file:

"proxies" : [ {
   "path"     : "/rssData",
   "proxyUrl" : "http://avolpe.github.io"
} ]

And call to /rssData/atom.xml instead of the real URL. Read more about ionic proxies here

Example with a Ionic List

If you use the previous code with a Ionic List, you can achieve a nice looking view of your rss, something like this:

With this html:

{{ entry.image }}
 <ion-list>
   <ion-item ng-repeat="entry in entries" class="item-avatar">
     <img ng-src="{{ entry.image }}" />
     <h2>{{ entry.title }}</h2>
     <p>{{ entry.url }}</p>
   </ion-item>
 </ion-list>

Currency evolution in Paraguay

Mon, 08 Feb 2016 00:00:00 +0000

The Central Bank of Paraguay publish the most relevant currency quotes every month in their Cotización Referencia Mensual page.

The page has two options to get the data, a pdf per month and year, or a ajax request per month and year. Because the pdf option require manual labor to extract and process the data, I choose the ajax way.

The request is very simple, something like this:

var request = {
  url       : "https : //www.bcp.gov.py/webapps/web/cotizacion/monedas-mensual",
  form_data : {
    anho : YEAR,
    mes  : MES
  }
}

With this simple python script I can get all the quotes from

To get the updated data, execute:

python3 scrapper.js > full_data.csv

This script generates a csv with one line per quote per month and per year, so you need to convert the data to use a service la Plot.ly. For example, I use LibreOffice with the PivotTable feature to group the data by currency and year, and then plot the data:

Note that the plot don’t show all the available currencies, to show an specific currency, click the name in the right menu.