Gigsterous blog

Spring Boot example auth server

Fri, 29 Jun 2018 13:00:00 +0000

In the past, we discussed various techniques for writing a Spring Boot application, including security, REST api etc. We proudly announce the release of the most complex Spring Boot authorization example so far. Feel free to check out our GitHub repository.

Here is a list of features supported by the auth server:

Username and password Authentication
OAuth2 Access + Refresh Token Provision
Registration with e-mail confirmation
Basic account management including password change, forgotten password, e-mail change and account deletion
Multilingual support
Logout including token invalidation
Easy SonarQube, Jacoco and Checkstyle integration for code-quality monitoring
Basic unit and integration test coverage with example tests

This example is written in Spring Boot 2 and we will try to maintain it to keep up with the latest changes. In case you wish to contribute or ask a question, we will be happy to discuss it with you on GitHub!

Spring Data REST and projections

Fri, 26 Jan 2018 13:00:00 +0000

Have you heard? 📣 We released a full-feature implemented auth server built on Spring-Boot 2. State-of-the-art OAuth2 provider and on top of that - fully open sourced! 🎉🛠

Go check out the blog post and then the repository as well! Happy hacking! 💻

Using Spring Data REST can get your API up and running in minutes and save you tons of work and coding…until you have a special use-case requiring you to spend a whole afternoon crawling the web for how to achieve that one missing piece of functionality.

In this post, I would like to share with you how to use projections. My use-case was quite simple:

Let’s have two entities: Cycle and Record.

Cycle contains list of records:

@Entity
@Table(name="cycles")
public class Cycle {

  @Id
  @GeneratedValue(strategy = GenerationType.AUTO)
  private long id;
  
  ...
  
  @OneToMany(mappedBy = "cycle", cascade = CascadeType.ALL)
  private List<Record> records;
}

@Entity
@Table(name = "records")
public class Record {

  @Id
  @GeneratedValue(strategy = GenerationType.AUTO)
  private long id;

  ...

  @ManyToOne
  @JoinColumn(name = "cycle_id")
  private Cycle cycle;
}

Both these entities have corresponding repositories:

@RepositoryRestResource
public interface CycleRepository extends PagingAndSortingRepository<Cycle, Long> {
}

@RepositoryRestResource
public interface RecordRepository extends JpaRepository<Record, Long> {
}

Since we are using Spring Data REST, these repositories are automatically exposed via REST API in HAL/JSON format. This is what a sample response for GET /cycles/1 looks like by default:

{
    "id": 1,
    ...
    "_links": {
        "self": {
            "href": "http://localhost:8008/cycles/1"
        },
        "records": {
            "href": "http://localhost:8008/cycles/1/records"
        }
    }
} 

But what if we want to get all record objects as part of the cycle instead of providing just a HAL link? The answer is @Projection! Projections allow us to alter the view model of our data. Following the official documentation, we can define what we want the response to look like:

@Projection(name = "inlineRecords", types = { Cycle.class })
public interface InlineRecords {

  long getId();

  // other getters
  ...

  List<Record> getRecords();
}

Adding this projection to our CycleRepository is quite easy:

@RepositoryRestResource(excerptProjection = InlineRecords.class)

When sending a request to fetch a specific cycle, we can specify which projection to use: GET /cycles/1?projection=inlineRecords:

{
    "id": 1,
    ...
    "_records": [
        .. records
    ],
    "_links": {
       ... links
    }
} 

The only problem is that, by default, Spring Data REST applies these projections to all _embedded data so when you request all cycles using GET /cycles, our inline projection will be used. That means that we will have all our records unwrapped in every cycle which could potentially be a very long response.

Fortunately, there is an alternative way how to register a projection and that is by using RepositoryRestConfigurerAdapter:

@Configuration
public class RepositoryConfig extends RepositoryRestConfigurerAdapter {

  @Override
  public void configureRepositoryRestConfiguration(RepositoryRestConfiguration config) {
    config.getProjectionConfiguration().addProjection(InlineRecords.class);
  }
}

This way, we can choose when the projection should be applied:

GET /cycles
GET /cycles?projection=inlineRecords
GET /cycles/{id}
GET /cycles/{id}?projection=inlineRecords

It is not hundred percent clear from the documentation what is the default behavior when considering different ways of using projections so I hope that this post might have saved you some frenetic Googling when you found yourself in need of this functionality.

Stress testing secured application with JMeter

Mon, 07 Aug 2017 13:00:00 +0000

Recently, I found myself in need of stress testing an OAuth2 flow of an application while working for Berrycloud. What I needed to do was to test the login and logout processes (obtaining and revoking the access token) repeatedly.

The desired test should look as follows:

Obtain an access token
Perform a random request on some secured endpoint
Revoke the access token
Repeat 1.

There are multiple approaches to how to write such test case, but there is an excellent tool that does it out-of-the-box - JMeter:

The Apache JMeter application is open source software, a 100% pure Java application designed to load test functional behavior and measure performance. It was originally designed for testing Web Applications but has since expanded to other test functions.

– Apache JMeter documetation

First of all, simply download JMeter and launch the jar file. A default test plan is already open so let’s start modifying it. Right-click on it and create a new Thread group. In the thread group configuration, you can specify the number of threads to run this test case, number of iterations, duration/start time etc.

The whole test plan is basically a tree where you can attach and nest nodes to specify the workflow. Our next step is creating the first HTTP request for obtaining the access token under the thread group. I will demonstrate the configuration against a localhost environment in this post. Though, normally, you would stress test an application in production (Netflix way) or staging environment.

Typically, a /oauth/token endpoint is secured with a basic authorization that looks as follows: Basic <Base64 encoded clientId:clientSecret>. Additionally, grant_type needs to be specified. Let’s assume that we are using the password grant type with a user called ‘john’ and password ‘secret’:

Additionally, headers with basic auth and content type need to be specified as well. You can add additional configuration to the request by right-clicking on it and selecting the add option. In this case, we need an HTTP Header Manager:

If the request is configured correctly, you can now click run to execute it. You probably won’t see much in JMeter but we can add View Results Tree node for checking the reponse to see if the request was successful. Our next step is getting the access token from the JSON response. Let’s say that the response body looks like this:

{
    "access_token":"370592fd-b9f8-452d-816a-4fd5c6b4b8a6",
    "token_type":"bearer",
    "expires_in":43199,
    "scope":"read write"
}

JMeter has a post-processor called JSON Extractor which is exactly what we need. It lets us grab the access token and save it to a local variable that could be referenced in future requests. Let’s save it with the same name - access_token:

It seems that we are finished with our first request for obtaining the token. Now let’s create another HTTP request in a similar fashion. In this case, we want to hit a /principal endpoint and use the token for getting the secured content. We can reference the token we saved in the previous request with ${access_token} in the header manager:

Last but not least, let’s revoke the token so our flow is complete. Assuming that we have a /revoke-token endpoint, this can be done with an additional HTTP request:

Everything is ready to be run now. If we configured everything correctly, we can now set the desired number of threads and iterations and start the stress test. The results can be viewed under the View Results Tree node.

Summary

Today, we learned how JMeter can be used to stress test a certain request flow in a web application. Obviously, this is just a small piece of functionality that is bundled in JMeter and I do recommend reading through the official documentation. The capabilities for monitoring and debugging are very wide.

Integration testing OAuth2 security with Spring Boot and WireMock

Thu, 18 May 2017 17:00:00 +0000

Have you heard? 📣 We released a full-feature implemented auth server built on Spring-Boot 2. State-of-the-art OAuth2 provider and on top of that - fully open sourced! 🎉🛠

Go check out the blog post and then the repository as well! Happy hacking! 💻

Recently, I was working with a couple of Spring Boot services that authenticate against a separate auth server using spring-security-oauth2 package. All that is needed to hook the services to the server is placing security.oauth2.resource.userInfoUri=http://localhost:8080/principal in the application.properties and annotating one of the configuration classes with @EnableResourceServer. That’s it - now everytime someone makes a request to your service, a request will be made to the auth server which will check the validity of the Bearer token and return a principal with user information from the specified endpoint.

The challenging part was writing the integration tests (starting with the controller layer and all the filters before including security).

Let’s say you have an endpoint /hello which returns some String. Your integration test could look as follows:

@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
public class HelloControllerIT {

    @Autowired
    private TestRestTemplate testRestTemplate;
    
    @Test
    public void testHelloEndpoint() {
        HttpHeaders headers = new HttpHeaders();
        // place your headers here
        
        final ResponseEntity<String> response = testRestTemplate.exchange("/hello", HttpMethod.GET), new HttpEntity<>(headers), String.class);
                
        assertThat(response.getStatusCode(), is(HttpStatus.OK));
        assertThat(response.getBody(), is("Hello, World!"));
    }
}

In case your service is secured with OAuth2, you will likely get a 401 - Unauthorized response in this test. There are multiple ways how to get around this. Some of them are very straight forward (turning off the security in the test profile) and some of them can get pretty complex. Spring offers some ways for mocking OAuth2 security in the tests but it can be quite challenging to make it work.

WireMock

Here is where I find WireMock extremely helpful. This powerful mocking engine enables you to mock responses from an external server and it integrates beautifully with JUnit. Of course, it can do much more (like running as a standalone server and capturing/replaying server responses or acting as a proxy) but we will focus on how to use it for mocking security in this short tutorial.

First of all, add WireMock as a dependency to your project:

<dependency>
    <groupId>com.github.tomakehurst</groupId>
    <artifactId>wiremock-standalone</artifactId>
    <version>2.6.0</version>
    <scope>test</scope>
</dependency>

Now we only need to do a couple of modifications to our test class and everything should work like a charm. The idea is, that we will mock the response containing the principal from the auth server when running our tests. Spring security will automatically see that the principal object was fetched successfully and will inject it into the security context.

First of all, initialize WireMockRule

@Rule
public WireMockRule wireMockRule = new WireMockRule();

and configure your endpoint stub to return any principal you need.

stubFor(get("/principal")
                .willReturn(okJson("{\"username\":\"john\",\"authorities\":[{\"authority\":\"ROLE_USER\"}]}")));

By default, WireMock is running on localhost:8080 but you can change this in your test configuration.

This is what the whole test class looks with WireMock:

@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
public class HelloControllerIT {

    @Autowired
    private TestRestTemplate testRestTemplate;
    
    @Rule
    public WireMockRule wireMockRule = new WireMockRule();
    
    @Test
    public void testHelloEndpoint() {
        stubFor(get("/principal")
                .willReturn(okJson("{\"username\":\"john\",\"authorities\":[{\"authority\":\"ROLE_USER\"}]}")));
    
        HttpHeaders headers = new HttpHeaders();
        headers.add(HttpHeaders.AUTHORIZATION, "Bearer xyz123");
        
        final ResponseEntity<String> response = testRestTemplate.exchange("/hello", HttpMethod.GET), new HttpEntity<>(headers), String.class);
                
        assertThat(response.getStatusCode(), is(HttpStatus.OK));
        assertThat(response.getBody(), is("Hello, World!"));
    }
}

Don’t forget to put an authorization header with some bearer token (it could be anything since we are mocking it in our test) in your request headers. Otherwise, Spring will not try to fetch the principal if it is missing.

Your test should be passing now if you did everything correctly. Congratulations! As I mentioned earlier, WireMock is much more powerful than this so do take the time and take a look at its website or GitHub repository.

Spring Boot REST API (4) - Security with OAuth2

Wed, 01 Mar 2017 18:00:00 +0000

Have you heard? 📣 We released a full-feature implemented auth server built on Spring-Boot 2. State-of-the-art OAuth2 provider and on top of that - fully open sourced! 🎉🛠

Go check out the blog post and then the repository as well! Happy hacking! 💻

In this post, we will continue with development of our simple REST API. This time, the focus will be on security. It is not an uncommon scenario that certain resources (or all of them) need to be protected and accessible only by registered users. There are multiple ways how to secure REST APIs and we cannot say that one is better than the other - it all depends on what we are trying to achieve.

OAuth2 is a protocol (or authorization framework, as I prefer to refer to it) that describes a stateless authorization (that means we don’t need to maintain sessions between clients and our server). Before we jump to code examples, let me briefly explain how OAuth2 works. I will not go into exhaustive details since this has been already described elsewhere.

This protocol allows third party clients to access protected resources on behalf of the resource owner. There are four basic roles in OAuth2:

Resource owner - the owner of the resource - this is pretty self-explanatory :-)
Resource server - the server hosting all the protected resources
Client - the application accessing the resource server
Authorization server - the server that handles issuing access tokens to clients. This could be the same server as the resource server

Furthermore, there are two types of tokens:

access token, which usually has limited lifetime and enables the client to access protected resources by including this token in the request header
refresh token with longer lifetime used to get a new access token once it expires (without the need of sending credentials to the server again)

It is important to note, that OAuth2 should be used with HTTPS because it requires the client to exchange sensitive information with the server (tokens or credentials).

Clients need to be registered with the authorization server in order to receive their client-id and client-secret which are later used when requesting the access tokens. Each token has a scope which is defined by the user when communicating with the authorization server (e.g. the user authorizes the client application to access certain resources on the resource server).

There are four different grant types defined by OAuth2. These grant types define interactions between the client and the auth/resource server. More detailed information can be found here.

Authorisation code - redirection-based flow for confidential client, the client communicates with the server via user-agent (web browser etc.), typical for web servers
Implicit - typically used with public clients running in a web browser using a scripting language, does not contain refresh tokens, this grant does not contain authentication and relies on redirection URI specified during client registration to the auth server
Resource owner password credentials - used with trusted clients (e.g. clients written by the same company that owns the auth server), user credentials are passed to the client and then to the auth server and exchanged for access and refresh tokens
Client credentials - used when the client itself is the resource owner (one client does not operate with multiple users), client credentials are exchanged directly for the tokens

Spring Boot and OAuth2

Now that we have some grasp on the theory, let’s jump to our example. We will take our API from our last post (you can download the source code from github) and implement our own OAuth2 security. There will be multiple users in our system, each with privileges to edit and delete only their own resources. We will also demonstrate OAuth2 using the resource owner password credentials grant since it best matches our use case. Furthermore, for the sake of simplicity, we will have the resource server and auth server together as part of the same application.

Let us start by adding the necessary dependencies:

<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-security</artifactId>
</dependency>

<dependency>
	<groupId>org.springframework.security.oauth</groupId>
	<artifactId>spring-security-oauth2</artifactId>
	</dependency>
</dependencies>

By default, if we do not configure Spring security, our API will be secured by basic auth using username and password generated during application startup. However, we are going to configure our OAuth setup and add some test users to our in-memory database to see how it works.

First of all, add @EnableResourceServer to the main class:

@SpringBootApplication
@EnableResourceServer
public class App {
	public static void main(String[] args) {
		SpringApplication.run(App.class, args);
	}
}

@EnableResourceServer will turn our application into a resource server (enables Spring Security filter to authenticate requests via an incoming OAuth2 token). This secures everything in the server except for the oauth endpoints, e.g. /oauth/authorize.

Next, we need to create an entity representing a user. Spring security uses an interface called UserDetails to encapsulate the user information in Authentication object:

@Entity
@Table(name = "users")
public class User implements UserDetails {
	
	static final long serialVersionUID = 1L;
	
	@Id
	@GeneratedValue(strategy = GenerationType.AUTO)
	@Column(name = "user_id", nullable = false, updatable = false)
	private Long id;
	
	@Column(name = "username", nullable = false, unique = true)
	private String username;
	
	@Column(name = "password", nullable = false)
	private String password;
	
	@Column(name = "enabled", nullable = false)
	private boolean enabled;

	@Override
	public Collection<? extends GrantedAuthority> getAuthorities() {
		List<GrantedAuthority> authorities = new ArrayList<GrantedAuthority>();
		
		return authorities;
	}

	@Override
	public boolean isAccountNonExpired() {
		return true;
	}

	@Override
	public boolean isAccountNonLocked() {
		// we never lock accounts
		return true;
	}

	@Override
	public boolean isCredentialsNonExpired() {
		// credentials never expire
		return true;
	}

	@Override
	public boolean isEnabled() {
		return enabled;
	}

	@Override
	public String getPassword() {
		return password;
	}

	@Override
	public String getUsername() {
		return username;
	}
}

We can now add the SQL table definition and add some sample data into our SQL migration scripts:

CREATE TABLE users (
    user_id BIGINT PRIMARY KEY auto_increment,
    username VARCHAR(128) UNIQUE,
    password VARCHAR(256),
    enabled BOOL,
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

INSERT INTO users (user_id, username, password, enabled) VALUES 
	('1', 'peter@example.com', '$2a$10$D4OLKI6yy68crm.3imC9X.P2xqKHs5TloWUcr6z5XdOqnTrAK84ri', true),
	('2', 'john@example.com', '$2a$10$D4OLKI6yy68crm.3imC9X.P2xqKHs5TloWUcr6z5XdOqnTrAK84ri', true),
	('3', 'katie@example.com', '$2a$10$D4OLKI6yy68crm.3imC9X.P2xqKHs5TloWUcr6z5XdOqnTrAK84ri', true);

Notice, that we store the password in an encrypted form. Never, ever store your users’ passwords in plain text. Period (Oh, and also, don’t use SHA-1). It would be handy to be able to retrieve users from the database as well. For this, we will need a JPA repository and a UserDetailsService which will enable us to pull these user details in the security context.

public interface UserRepository extends JpaRepository<User, Long> {
	User findOneByUsername(String username);
}

@Service("userDetailsService")
public class UserService implements UserDetailsService {
	
	@Autowired
	private UserRepository userRepository;

	@Override
	public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {
		return userRepository.findOneByUsername(username);
	}
}

Notice that UserDetailsService needs to implement only one method - loadUserByUsername. This method is used to determine which user is logged in, asuming that every user has a unique username.

Now that we have the user infrastructure in place, we can hook it to our OAuth2 configuration:

@Configuration
@EnableAuthorizationServer
public class OAuth2Config extends AuthorizationServerConfigurerAdapter {

	@Autowired
	@Qualifier("userDetailsService")
	private UserDetailsService userDetailsService;

	@Autowired
	private AuthenticationManager authenticationManager;

	@Value("${gigy.oauth.tokenTimeout:3600}")
	private int expiration;

	@Bean
	public PasswordEncoder passwordEncoder() {
		return new BCryptPasswordEncoder();
	}

	@Override
	public void configure(AuthorizationServerEndpointsConfigurer configurer) throws Exception {
		configurer.authenticationManager(authenticationManager);
		configurer.userDetailsService(userDetailsService);
	}

	@Override
	public void configure(ClientDetailsServiceConfigurer clients) throws Exception {
		clients.inMemory().withClient("gigy").secret("secret").accessTokenValiditySeconds(expiration)
				.scopes("read", "write").authorizedGrantTypes("password", "refresh_token").resourceIds("resource");
	}
}

Let’s stop here for a moment and take a look at what’s going on. First of all, this is the first time we used @Configuration in our project. This annotation indicates that the annotated class contains bean definitions that will be loaded into Spring context. @EnableAuthorizationServer annotation will, similarly to @EnableResourceServer, let us use this application as an auth server.

Autowiring the UserDetailsService, that we added earlier, will enable us to use the users from our database in our auth server. AuthenticationManager is a Spring bean for handling the authenticated requests. We will not make any modifications to it in this part and will simply pass it to the configure method.

Notice that we have two methods with this name that are used for different purposes. The first one is used to hook up the users into the auth server (these come from our database - or from our in-memory mock data we created earlier) and the second one configures the clients (applications connecting to the server). In this case, there is only one in-memory client called ‘gigy’. Instead of hard-coding the clients in our configuration, we could use JDBC store, instead, but we are going to make it very simple in this tutorial.

This is everything we need to secure our server with OAuth2. Let’s give it a try!

Let’s try accessing some protected resource without authentication first:

curl -i -H "Accept: application/json" -X GET http://localhost:8000/gigy/people

This should result in an 401 error for unauthorized request. We need to get the auth token before sending requests to the protected endpoints. As we mentioned earlier, we are using the password grant type which means we are getting the token on behalf of a specific user so we need to send the user’s credentials to the auth server. In this case, our sample application is running on localhost but in production. This endpoint should be always contacted over HTTPS.

curl -X POST --user 'gigy:secret' -d 'grant_type=password&username=peter@example.com&password=password' http://localhost:8000/gigy/oauth/token

The following response with the access and refresh tokens will be produced:

{"access_token":"27c1d964-fcad-470f-b32b-219c662e6099","token_type":"bearer","refresh_token":"d7fe669c-cf46-46ee-b790-a9ef39ea7e63","expires_in":3599,"scope":"read write"}

We can now try to access the protected endpoint with our access token in the request headers:

curl -i -H "Accept: application/json" -H "Authorization: Bearer $TOKEN" -X GET http://localhost:8000/gigy/people

Getting security context

There are multiple ways how to retrieve the current security context in a Spring/Spring Boot application. A nice summary can be found, for example, here.

Since the Person entity represents our users, we first need to link it to the User object which is used by Spring security context. There are many ways to do that but we are going to simply use the username to associate these entities. It might not be the most elegant approach but it will do for our simple scenario. Let’s modify our database schema:

CREATE TABLE people (
    person_id BIGINT PRIMARY KEY auto_increment,
    name VARCHAR(32),
    username VARCHAR(128) UNIQUE REFERENCES users (username),
    age INT,
);

And don’t forget to modify the Person entity as well: private String username;. Finally, let us load people by their username:

@Repository
public interface PersonRepository extends CrudRepository<Person, Long> {
	Collection<Person> findAll();
	Person findByUsername(String username);
}

We are going to demonstrate how to access the currently logged-in user inside a controller. We already have an endpoint for deleting users in our application. However, the way it is implemented now allows anyone to delete any user. Let’s say that the person entity should be deleted only by it’s owner. This can be easily implemented by accessing the Principal object inside our controller:

@RequestMapping(value = "/{id}", method = RequestMethod.DELETE)
public ResponseEntity<Void> deletePerson(@PathVariable long id, Principal principal) {
	Person currentPerson = personRepo.findByUsername(principal.getName());
	
	if (currentPerson.getId() == id) {
		personRepo.delete(id);
		return new ResponseEntity<Void>(HttpStatus.OK);
	} else {
		return new ResponseEntity<Void>(HttpStatus.UNAUTHORIZED);
	}
}

Now, the logged-in user cannot delete any entities (people) that he does not own. We would probably need to update the other endpoints as well to make them work with the ‘current user’ functionality but I will leave that for you as an exercise :-)

Summary

Today, we learned how to protect our REST API using Spring Security and OAuth2. As always, you can download the working example from Git.

Spring Boot REST API (3) - Unit testing

Tue, 18 Oct 2016 17:00:00 +0000

Have you heard? 📣 We released a full-feature implemented auth server built on Spring-Boot 2. State-of-the-art OAuth2 provider and on top of that - fully open sourced! 🎉🛠

Go check out the blog post and then the repository as well! Happy hacking! 💻

We have already learned how to set up a simple REST API in Spring Boot and create a relational model of our entities. This time, we will take a look at how to write unit tests for all layers in our application.

Spring Boot provides many useful annotations and tools for testing. Things have got significantly easier starting in Spring Boot 1.4. We already have spring-boot-starter-test dependency in our project, so if you don’t simply include this in your pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
</dependency>

This module includes a lot of useful testing tools - you can see the full list in the official documentation.

Testing without Spring context

It is considered a good practice to structure your code in a way that enables you to test individual components of your system separately. Not only that - ideally also without any Spring context. This can be achieved e.g. by constructor injection. Constructor injection allows initializing the components using the new keyword rather than having to @Autowire them in our unit tests.

We do not have any services in our application yet, so let’s create one and then write a unit test for it (or preferably the other way around if you want to do TDD). Our service will be a very simple piece of code that takes a person as an input parameter and finds another one (a buddy) using PersonRepository.

First, we will create an interface (it is good practice to use an interface for every service when working with Spring):

public interface BuddyService {
	public Person findBuddy(Person person);
}

And now let’s crate our service implementation:

@Service
public class DrinkingBuddyService implements BuddyService {
	private PersonRepository repository;
	
	@Autowired
	public DrinkingBuddyService(PersonRepository repository) {
		this.repository = repository;
	}

	/**
	 * Finds and returns person with smallest age difference to the input.
	 */
	@Override
	public Person findBuddy(Person person) {
		Person buddy = null;
		
		for (Person p : repository.findAll()) {
			// do not return same person or person without age
			if (p.getId() == person.getId() || p.getAge() == 0) {
				continue;
			}
			
			// no buddy? Take the first one
			if (buddy == null) {
				buddy = p;
			}
			
			int buddyDiff = Math.abs(person.getAge() - buddy.getAge());
			int currentDiff = Math.abs(person.getAge() - p.getAge());
			
			// found someone closer to this person's age
			if (currentDiff < buddyDiff) {
				buddy = p;
			}
		}
		
		return buddy;
	}
}

This code logic might not be the best you’ll ever see, but it is easy to understand and sufficient for demonstrating how a test can be written for Spring services. Furthermore, notice the @Service annotation in our class. This annotation registers our class as a Spring component and lets us inject it into Spring context using the following construct (same as our repositories):

@Autowire
BuddyService buddyService;

We also inject our PersonRepository to our service in constructor, because we want to be able to write a test that will inject it using a classic constructor (hence, without the Spring context).

Let’s take a look at what our test could look like:

public class DrinkingBuddyServiceTest {
	
	private PersonRepository repository;
	private DrinkingBuddyService service;
	
	@Before
	public void prepare() {
		repository = mock(PersonRepository.class);
		service = new DrinkingBuddyService(repository);
	}
	
	@Test
	public void findBuddyTest() {
	    List<Person> people = new ArrayList<Person>();
	    
	    Person p1 = new Person();
	    p1.setId(1l);
	    p1.setName("John");
	    p1.setAge(25);
	    people.add(p1);
	    
	    Person p2 = new Person();
	    p2.setId(2l);
	    p2.setName("Marry");
	    p2.setAge(22);
	    people.add(p2);
	    
	    Person p3 = new Person();
	    p3.setId(1l);
	    p3.setName("Peter");
	    p3.setAge(35);
	    people.add(p3);
	    
	    when(repository.findAll()).thenReturn(people);
	    
	    assertEquals(service.findBuddy(p1), p2);
	}
}

One important concept to keep in mind when writing unit tests is that we want to isolate the tested class and test only one layer of the application at a time. That’s why we mock the repository and prepare a predefined response for findAll() to be returned when it gets called. This is achieved using Mockito which is part of the Spring test module. All we have to do is to call the method from DrinkingBuddyService we are testing and assert that the response is as expected.

Context slicing

Testing without Spring context is fast and useful but it cannot be done that way in all situations. Sometimes, we need to have a SpringContext to test some parts of our application. Starting in Spring Boot version 1.4, we can make a use of slicing feature, which launches only the part of Spring context that we need.

You can, of course, still launch the whole Spring context using @SpringBootTest annotation when performing integration testing. We will not go into details on this topic, though.

Testing controllers

To test our controllers, we need to launch the WebMvc context slice. Ideally, we should only load the single controller we are going to test instead of the whole web layer. This can be done easily with @WebMvcTest annotation:

@RunWith(SpringRunner.class)
@WebMvcTest(PersonController.class)
public class PersonControllerTest {

	@Autowired
	private MockMvc mvc;

	@MockBean
	private PersonRepository personRepo;

	@Test
	public void getPersonTest() throws Exception {
	    Person person = new Person();
	    person.setId(1l);
		person.setName("John");
		person.setAge(25);
	
		given(personRepo.findOne(1l)).willReturn(person);
		mvc.perform(get("/people/1").accept(MediaType.APPLICATION_JSON_VALUE)).andExpect(status().isOk())
				.andExpect(jsonPath("$.id", is(1)))
				.andExpect(jsonPath("$.name", is("John")))
				.andExpect(jsonPath("$.age", is(25)));
	}
	
	@Test
	public void personNotFoundTest() throws Exception {
		mvc.perform(get("/people/2").accept(MediaType.APPLICATION_JSON_VALUE)).andExpect(status().isNotFound());
	}
}

Let’s stop for a while and see what we just did here. By adding @RunWith(SpringRunner.class) to our test class, we tell JUnit to start running using Spring’s testing support. Furthermore, @WebMvc(PersonController.class) specifies that WebMvc context will be launched only with PersonController class initialized.

We need to autowire the MockMvc bean, because we need to mock some requests for our endpoint in our test. Finally, PersonRepository needs to be mocked and provided as a bean to our context, because it is autowired in the tested PersonController and Spring would complain about this bean being missing otherwise (Spring loads everything that is needed in order to initialize this controller into the context). Why mock it and not load it into the context as well? Well, we are testing only one layer (controller, in this example) at a time, remember?

The rest of this test is very straight-forward. We make request to our endpoint using MockMvc and examine the response. One thing that is probably worth pointing out is the jsonPath method which comes from Hamcrest and lets us check various parts of the JSON response.

Testing JPA repositories

Another thing we can test are our repositories. There is another useful context slice just for this layer: @DataJpaTest. Let’s take a look at what this test could look like:

@RunWith(SpringRunner.class)
@DataJpaTest
public class PersonRepositoryTest {

    @Autowired
    private PersonRepository repository;

    @Test
    public void repositorySavesPerson() {
        Person person = new Person();
        person.setName("John");
        person.setAge(25);
        
        Person result = repository.save(person);
        
        assertEquals(result.getName(), "John");
        assertEquals(result.getAge(), 25);
    }
}

Please note, that this test is very simple and does not test EntityManager explicitly. It is here just to demonstrate the basic test skeleton and custom JPA slice, which provides the data layer to the context.

More context slices

Our application is still quite simple so we will not be showing all the available context slices but they are worth mentioning nonetheless:

@JsonTest - JSON serialization and deserialization
@RestClientTest - REST clients testing
@AutoConfigureRestDocs - Spring REST Docs testing

Summary

In this part of Spring Boot REST API series, we learned how to write simple unit tests for various layers of our application and explored how Spring context slicing can be used to make our tests easier and faster to run. As always, up-to-date code of the example application can be downloaded from GitHub.

Spring Boot REST API (2) - JPA relationships

Sun, 25 Sep 2016 17:00:00 +0000

Have you heard? 📣 We released a full-feature implemented auth server built on Spring-Boot 2. State-of-the-art OAuth2 provider and on top of that - fully open sourced! 🎉🛠

Go check out the blog post and then the repository as well! Happy hacking! 💻

In the previous part of this series, we created a tiny API in Spring Boot which exposes people entities over REST. There are usually many resources with (sometimes quite complicated) relationships between each other in a typical web application. In this part, we are going to examine how such relationships can be easily implemented in Spring Boot and Hibernate.

We are going to continue with the project we created last time. If you do not have it and would like to follow this tutorial, you can download it here or get the final result instead.

The good thing is that no additional dependencies are needed since we already have JPA (which contains Hibernate) in the project so we can jump straight into coding.

Entities

We will introduce some new entities in our application to make the schema a bit more complex. Let’s say that our application will provide information about people going to various parties where each person will have some set of skills. The data model will looks as follows:

Let’s start by updating our schema.sql:

CREATE TABLE people (
    person_id BIGINT PRIMARY KEY auto_increment,
    name VARCHAR(32),
    age INT,
);

CREATE TABLE skills (
    skill_id BIGINT PRIMARY KEY auto_increment,
    person_id BIGINT REFERENCES people (person_id),
    name VARCHAR(16),
    level VARCHAR(16)
);

CREATE TABLE parties (
    party_id BIGINT PRIMARY KEY auto_increment,
    location VARCHAR(64),
    party_date TIMESTAMP,
);

CREATE TABLE people_parties (
  person_id BIGINT NOT NULL REFERENCES people (person_id),
  party_id BIGINT NOT NULL REFERENCES parties (party_id),
  PRIMARY KEY (person_id, party_id),
);

One-to-Many

The first relationship we will take a look at is a type one-to-many. In other words, one entity will have a reference to many entities of certain type. As described in the diagram above, we can see that each person has a set of skills. In this case, the skill entity is the owner of the relationship since it contains the link to its person.

We can handle this case in JPA by simply putting this reference in the Person.java:

@OneToMany(mappedBy = "person")
private Set<Skill> skills = new HashSet<Skill>();

We also have to create the Skill.java object for the skill entity and put the necessary mappings in there as well:

@Entity
@Table(name = "skills")
public class Skill {

	@Id
	@GeneratedValue(strategy = GenerationType.AUTO)
	@Column(name = "skill_id")
	private long id;

	private String name;

	@Enumerated(EnumType.STRING)
	private Level level;

	@ManyToOne
	@JoinColumn (name="person_id")
	@JsonBackReference
	private Person person;
    
    // getters and setters
}

Furthemore, we specified a level for each skill which is an enum value (to have a predefined set of values instead of random “magical” values). Let’s go ahead and create it in Level.java:

public enum Level {
	GOOD, AWESOME, GODLIKE
}

There are several things worth explaining in the code we just created. First of all, as mentioned above, we are going to limit the set of values for each skill level by using an enum. There are two ways how to map enums from database to POJOs:

EnumType.STRING
EnumType.ORDINAL

The first one will require to save strings that match our enum values to the database (eg. ‘GOOD’) whereas the second one uses integer values matching the position in our enum list (eg. 0 would refer to GOOD). There are pros and cons for both approaches but I would personally prefer EnumType.STRING since an addition of some additional new value would not corrupt the existing data. In contrast, if we prepend POOR to the list and use EnumType.ORDINAL, all our database entries will get out of sync.

Second thing to notice is the @JoinColumn annotation, where we specify the name of the column that contains the mapped object’s foreign key. Since Skill is the owner of this relationship, the mapping is done here. In the Person object, we simply specify where its foreign key is stored using @OneToMany(mappedBy = 'person').

Lastly, we put @JsonBackReference on the person reference in the Skill object. When exposing these resources via REST, we need to avoid recursive relationships in JSON and without this annotation (or @JsonIgnore) we would create an infinite loop of nested objects in our response. This annotation basically says that a person will not be part of the JSON returned for skill (but each person will contain list of its skills in the response). If the person was a part of the list then the program would fetch the person’s skills, which would then make the program fetch the person again and again until we’d get a StackOverflowException.

Many-to-Many

Next relationship we are going to model is many-to-many. People will be linked to various parties that they will/did attend - one person can go to multiple parties and each party can have multiple visitors. In our SQL script, we have to model this relationship using a relationship table called people_parties:

CREATE TABLE parties (
    party_id BIGINT PRIMARY KEY auto_increment,
    location VARCHAR(64),
    party_date TIMESTAMP,
);

CREATE TABLE people_parties (
  person_id BIGINT NOT NULL REFERENCES people (person_id),
  party_id BIGINT NOT NULL REFERENCES parties (party_id),
  PRIMARY KEY (person_id, party_id),
);

Again, we have to create the object for a party in Party.java:

@Entity
@Table(name = "parties")
public class Party {

	@Id
	@GeneratedValue(strategy = GenerationType.AUTO)
	@Column(name = "party_id")
	private long id;

	private String location;

	@Column(name = "party_date")
	@JsonFormat(pattern = "YYYY-MM-dd")
	private Date date;

	@ManyToMany
	@JoinTable(name = "people_parties", 
		joinColumns = @JoinColumn(name = "party_id", referencedColumnName = "party_id"), 
		inverseJoinColumns = @JoinColumn(name = "person_id", referencedColumnName = "person_id"))
	private Set<Person> people = new HashSet<Person>();
	
	// getters and setters
}

and also add this mapping to Person.java:

@ManyToMany(cascade = CascadeType.ALL)
@JsonBackReference
@JoinTable(name = "people_parties",
	joinColumns = @JoinColumn(name = "person_id", referencedColumnName = "person_id"),
	inverseJoinColumns = @JoinColumn(name = "party_id", referencedColumnName = "party_id"))
private Set<Party> parties = new HashSet<Party>();

The relationship table is mapped to our objects using @JoinTable annotation. The name of this table has to be specified along with joinColumns (mapping for composite foreign keys) and optionally inverseJoinColumns (the foreign key columns of the join table that reference the primary table of the entity that does not own the association).

And finally, if we are going to expose these entities via REST, we need to avoid the infinite recursion in the JSON responses here as well. We’ll accomplish that by putting @JsonBackReference on one side of the relationship. In this case, all responses for parties will also include people in them but not vice versa.

Adding controller and testing

The application should now compile but parties are not yet publicly exposed. In order to do that, we first need to create repository for them (same way we did in the first part):

@Repository
public interface PartyRepository extends CrudRepository<Party, Long> {
	Collection<Party> findAll();
}

and also create a controller:

@RestController
@RequestMapping("/parties")
public class PartyController {

	@Autowired
	private PartyRepository partyRepo;

	@RequestMapping(method = RequestMethod.GET)
	public ResponseEntity<Collection<Party>> getParties() {
		return new ResponseEntity<>(partyRepo.findAll(), HttpStatus.OK);
	}

	@RequestMapping(value = "/{id}", method = RequestMethod.GET)
	public ResponseEntity<Party> getParty(@PathVariable long id) {
		Party party = partyRepo.findOne(id);

		if (party != null) {
			return new ResponseEntity<>(partyRepo.findOne(id), HttpStatus.OK);
		} else {
			return new ResponseEntity<>(null, HttpStatus.NOT_FOUND);
		}
	}

	@RequestMapping(method = RequestMethod.POST)
	public ResponseEntity<?> addParty(@RequestBody Party party) {
		return new ResponseEntity<>(partyRepo.save(party), HttpStatus.CREATED);
	}

	@RequestMapping(value = "/{id}", method = RequestMethod.DELETE)
	public ResponseEntity<Void> deletePartyn(@PathVariable long id) {
		partyRepo.delete(id);

		return new ResponseEntity<Void>(HttpStatus.OK);
	}
}

Let’s also pre-populate our database with some data to test our new service. We can do this in our data.sql:

INSERT INTO skills (skill_id, person_id, name, level) VALUES
	(1, 1, 'Juggling', 'GOOD'),
	(2, 1, 'Dancing', 'AWESOME'),
	(3, 2, 'Juggling', 'AWESOME'),
	(4, 2, 'Story-telling', 'GODLIKE'),
	(5, 3, 'Singing', 'GOOD');

INSERT INTO parties (party_id, location, party_date) VALUES 
	(1, 'Old Folks Club', '2016-09-20'),
	(2, 'Luxury Yacht Party', '2016-12-05');
	
INSERT INTO people_parties (person_id, party_id) VALUES
	(1, 1),
	(1, 2),
	(2, 1),
	(3, 2);

Now we are finally ready to run the application and test the outcome at localhost:8000/gigy/parties and localhost:8000/gigy/people. You should see that people now have set of skills in every response and the responses with parties contain the people attending them.

Notice, that people are part of each party in the JSON response:

{
   "id": 1,
   "location": "Old Folks Club",
   "date": "2016-09-19",
   "people": [
     {
       "id": 2,
       "name": "John",
       "age": 30,
       "skills": [
         {
           "id": 3,
           "name": "Juggling",
           "level": "AWESOME"
         },
         {
           "id": 4,
           "name": "Story-telling",
           "level": "GODLIKE"
         }
      ]
     },
     {
       "id": 1,
       "name": "Peter",
       "age": 25,
       "skills": [
         {
           "id": 1,
           "name": "Juggling",
           "level": "GOOD"
         },
         {
           "id": 2,
           "name": "Dancing",
           "level": "AWESOME"
         }
       ]
     }
   ]
 }

It does not work vice versa for the /people endpoint since we added the @JsonBackReference but we can implement a separate endpoint for accessing parties for a given person:

@RequestMapping(value = "/{id}/parties", method = RequestMethod.GET)
public ResponseEntity<Collection<Party>> getPersonParties(@PathVariable long id) {
	Person person = personRepo.findOne(id);

	if (person != null) {
		return new ResponseEntity<>(person.getParties(), HttpStatus.OK);
	} else {
		return new ResponseEntity<>(null, HttpStatus.NOT_FOUND);
	}
}

Summary

In this part of the Spring Boot REST API series, we covered how to specify one-to-many and many-to-many relationship between our entities in order to demonstrate how to expose some more complex data via REST. The purpose of this post was to give a higher level tutorial for this topic rather than to examine in-depth JPA and Hibernate capabilities. The resulting service we just created can be donwloaded from Github. Feel free to use it as a starting position for your next project, because it’s published under Apache License 2.0.

Sidenote

Instead of writing our own controllers, we could make use of spring-boot-data-rest starter which converts all JPA repositories into a fully functional RESTful API with responses in HAL/JSON. However, we implemented the controllers manually to demonstrate how to work with them and we will continue to use them in the following parts of this series. If you need a guide for using spring-boot-data-rest you can find it in official resources.

Spring Boot REST API (1) - Project setup

Wed, 14 Sep 2016 17:00:00 +0000

Have you heard? 📣 We released a full-feature implemented auth server built on Spring-Boot 2. State-of-the-art OAuth2 provider and on top of that - fully open sourced! 🎉🛠

Go check out the blog post and then the repository as well! Happy hacking! 💻

This is the first part of my series on building a REST API with Spring Boot. Although there are many tutorials on this manner on the internet, my goal is to provide a step-by-step guide for designing the web application from scratch and gradually add more functionality to it in the next parts of this series.

In this tutorial, we are going to start simple and create a small Spring Boot app exposing one entity over REST. We will also setup a test environment with in-memory database to prepopulate our API with some data.

You can either follow the tutorial on your own or download the source code used in this blog post from Github.

Starting the project

First, create a Spring Boot app in our IDE (if supported) or download a basic skeleton from SpringInitializr and import it. We will be using Spring Boot 1.4 and Maven in this tutorial.

Open your pom.xml and add the following dependencies:

<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
	<groupId>com.h2database</groupId>
	<artifactId>h2</artifactId>
	<scope>runtime</scope>
</dependency>
<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-test</artifactId>
	<scope>test</scope>
</dependency>

spring-boot-starter-data-jpa provides easy access to relational database
spring-boot-starter-web is needed for building web (and RESTful) applicaations, contains embedded Tomcat as a servlet container
spring-boot-starter-test includes various test libraries including JUnit, Mockito, etc.
h2 provides databse engine for our application

Data model

In this tutorial, we will create a simple web application with one entity - people - exposed via REST. Let’s start by creating the class representing our model:

@Entity
@Table(name = "people")
public class Person {

	@Id
	@GeneratedValue(strategy = GenerationType.AUTO)
	@Column(name = "person_id")
	private long id;

	private String name;
	private int age;

	public Person() {
		// empty constuctor for Hibernate
	}

	public long getId() {
		return id;
	}

	public void setId(long id) {
		this.id = id;
	}

	public String getName() {
		return name;
	}

	public void setName(String name) {
		this.name = name;
	}

	public int getAge() {
		return age;
	}

	public void setAge(int age) {
		this.age = age;
	}
}

We will also create the SQL script for creating the table for our entity and prefill some data in it. Spring Boot lets us do this easily by placing schema.sql and data.sql scripts in the root of the resources directory (next to application.properties). By default, in-memory H2 database will be used. We could change this and hook our service to a real database by specifying it in application.properties.

Create these scripts and put the following code into schema.sql:

CREATE TABLE people (
    person_id BIGINT PRIMARY KEY auto_increment,
    name VARCHAR(32),
    age INT,
);

Lets also prefill some data to our database in data.sql:

INSERT INTO people (person_id, name, age) VALUES 
	('1', 'Peter', 25),
	('2', 'John', 30),
	('3', 'Katie', 18);

Finally, we will do some modifications in our application.properties. Te following changes are not necessary to run this project but will demonstrate how we can customize the application entry point and port:

server.port=8000
server.contextPath=/gigy

Creating REST controller

Finally, lets create a controller for accessing the data via REST. Creating controllers can be done easily in Spring by placing @RestController on a class. @RequestMapping annotation is then used for specifying the endpoint properties including path, Http method, content type etc.

@RestController
@RequestMapping("/people")
public class PersonController {

	@Autowired
	private PersonRepository personRepo;

	@RequestMapping(method = RequestMethod.GET)
	public ResponseEntity<Collection<Person>> getPeople() {
		return new ResponseEntity<>(personRepo.findAll(), HttpStatus.OK);
	}

	@RequestMapping(value = "/{id}", method = RequestMethod.GET)
	public ResponseEntity<Person> getPerson(@PathVariable long id) {
		Person person = personRepo.findOne(id);

		if (person != null) {
			return new ResponseEntity<>(personRepo.findOne(id), HttpStatus.OK);
		} else {
			return new ResponseEntity<>(null, HttpStatus.NOT_FOUND);
		}
	}

	@RequestMapping(method = RequestMethod.POST)
	public ResponseEntity<?> addPerson(@RequestBody Person person) {
		return new ResponseEntity<>(personRepo.save(person), HttpStatus.CREATED);
	}

	@RequestMapping(value = "/{id}", method = RequestMethod.DELETE)
	public ResponseEntity<Void> deletePerson(@PathVariable long id) {
		personRepo.delete(id);
		
		return new ResponseEntity<Void>(HttpStatus.OK);
	}
}

Testing the service

We are ready to test the outcome yet. Run the application and try accessing, modifying and deleting data by accessing these REST endpoints:

GET

curl -i -H "Accept: application/json" -H "Content-Type: application/json" -X GET http://localhost:8000/gigy/people

should return all the entities in our database in JSON format.

POST

curl -H "Content-Type: application/json" -X POST -d '{"name":"Mark","age":40}' http://localhost:8000/gigy/people

DELETE

curl -X DELETE http://localhost:8000/gigy/people/2

Summary

In this tutorial, we covered a basic project setup with in-memory database accessed by JPA and accessin its data via REST. This project will be used as a base for the next parts of this series which will cover more topics about building a RESTful API.

Travis CI for iOS projects

Tue, 13 Sep 2016 17:00:00 +0000

In the past couple days I tried to find the most exhaustive tutorial that would tell me how to set up Travis CI for our iOS project in a reasonable amount of time. I didn’t want anything fancy, anything out of the ordinary, just a simple step-by-step tutorial that would lead me to the desired outcome. No luck, so here it is - how to set Travis up from start to finish for an iOS project.

Project components

Usual suspects:

Swift project
CocoaPods
GitHub

What am I trying to achieve?

To start with, I would like to set up a pipeline for automatic project building and code check. Later on, I would like to add automatic test scheduling and deployment to beta testers or the App Store. It’s important to get the repetitive work out of the way as soon as possible. If a server can do it automatically, don’t do it yourself. Save precious time for tedious bugs.

Travis website

First, you have to register on the Travis CI website. Because our project is hosted on GitHub and Travis is neatly integrated with GitHub, go for Sign in with GitHub. By signing in you give consent to Travis to:

Read org and team membership
Access commit status
Access deployment status
Access user email addresses (read-only)
Write repository hooks

In fact this is nothing unusual as most CI tools require these in order to function properly. You can read more about third-party access here. Little side note - to be able to allow Travis in an organizational repo, you have to be the Owner (have full access rights in the organization).

Travis project setup

Once you’ve signed in, you can see all your repositories and organizations. Find your repository and click the switch where you want to allow Travis to operate.

When you’ve done that, click the gear icon to proceed to settings. I personally prefer to turn on the option Build only if .travis.yml is present. I don’t want it to do anything before I’ve told it exactly what to do (.travis.yml is the “recipe” for Travis). Otherwise Jekyll starts a default image and build recipe which may be totally useless anyway. That’s pretty much it for now regarding the website. Don’t close it yet, just leave the tab open - we’ll come back to it in a minute.

Revoking access

In case you ever feel like revoking the access for Travis, simply go to Profile > Settings > OAuth applications and there you’ll find the whole list of all authorized applications.

We’re not here to revoke access, but rather to grant it! I do feel obliged to tell you though, in order for this tutorial to really be complete.

Project setup

Before we open Xcode there is one important thing to go through. That is: what do you actually have in your repository. Yes, I’m talking about ignored files. There have been endless debates over whether or not to have Pods in your repo…that some people don’t have CocoaPods installed and thus wouldn’t be able to run the code immediately. No, just no. Stop right there. Would you sync Maven dependencies? I thought so.

Our .gitignore looks like this:

.DS_Store
build/
*.pbxuser
!default.pbxuser
*.mode1v3
!default.mode1v3
*.mode2v3
!default.mode2v3
*.perspectivev3
!default.perspectivev3
*.xcworkspace
!default.xcworkspace
xcuserdata
profile
*.moved-aside
DerivedData
.idea/
Pods

I found it on Stack Overflow a couple years back and it has never failed me. Also, by incorporating Travis in your CI pipeline, you pretty much test every time that the dependencies are downloaded correctly and that the project builds correctly.

Podfile

As you probably know, but in case you didn’t, starting with CocoaPods 1.0 you always have to define your target in your Podfile. Nothing hard, actually. Ours looks like this:

platform :ios, '9.0'
use_frameworks!

target "Gigsterous" do
  pod 'MBProgressHUD', '~> 0.9.1'
end

Xcode

This part of the tutorial was the one that was somehow kept secret from me and why I wasn’t able to build the project on Travis. Whenever you want to have a project be automatically built along with CP dependencies, you have to add them to the scheme. Scheme? What? No worries, I got you covered. To find schemes of your app go to Product > Scheme > Manage Schemes…:

Make sure the scheme is Shared, then mark it and hit the Edit… button. From there, select the Build option in the left pane. You may notice that in the Targets section in the middle pane something is missing - YES, none of the Pods are there. So go ahead, hit the left bottom plus button and add all your Pods to the build scheme. Then, grab all pod-related targets and move them to the top of the list. You should end up with something very similar to this:

Travis YAML file

The last component that puts it all together is the “recipe” for Travis to use. It’s essentially a configuration file listing all the steps and necessary pre-conditions for a successful build to happen. You can also include multiple goodies such as SwiftLint or your unit tests.

So what is it? It’s just a simple YAML file, neatly structured into logical blocks. Ours looks like this:

language: objective-c
osx_image: xcode7.3

branches:
  only:
    - develop
    - master
env:
  - LC_CTYPE=en_US.UTF-8 LANG=en_US.UTF-8
before_install:
  - rvm install ruby-2.2.2
  - gem install cocoapods
  - gem install xcpretty -N
  - brew update
  - brew install swiftlint || true
script:
  - set -o pipefail
  - xcodebuild -workspace Gigsterous.xcworkspace -scheme Gigsterous -sdk iphonesimulator ONLY_ACTIVE_ARCH=NO | xcpretty -c
  - swiftlint

It can get waaaay more complicated, but this one works for us for now. Let’s break it down block by block:

The top always includes the top level specification - language and platform. In our case it’s an objective-c/swift and xcode7.3 environment. Xcode 8 is currently in beta in Travis, but as soon as it’s live, we’ll switch over as well.
Next you define which branches you want Travis to build (including incoming pull requests). As you may have noticed, we are using the full gitflow.
Optionally you can specify extra requirements for your environment. I personally prefer when the image is a clean UTF-8 environment.
Many things can happen before the actual build. In our case, we make sure we have the right version of Ruby in order to have CocoaPods 1.0 fully functional and we also install a great formatting tool called xcpretty to make the logs coming out of xcodebuild a bit more readable.
And at the very end is the script - nothing fancy, sets the pipefail, calls the build and then performs lint check to make sure our code is not only running well, but also in a good condition.

And that should do it! Feel free to adjust/delete/add anything and add it to your code to make it as smooth as possible. If you have a simple git workflow (commit + push straight to master), then there’s no catch - go ahead, push and enjoy. If you have multiple branches it can get a bit tricky because since we turned Travis off in the event of .travis.yml file being missing, turning it back on doesn’t trigger the build. You first have to enable it, then push again into the PR branch and then it will trigger the build. If you just push into the master, it will naturally start building automatically as well.

Summary

That’s it for today! I hope this post helped you with your first Travis setup. I’m almost 100% sure we went through every step in order to be successful with Travis. If something doesn’t sound right or if you have any questions, feel free to drop me a tweet!