Projeto: app Amphibians

1. Antes de começar

Este codelab apresenta um novo app, chamado Amphibians, que você vai criar por conta própria. O codelab mostra os passos para concluir o projeto do app Amphibians, incluindo a configuração dele e os testes no Android Studio.

Pré-requisitos

  • Este projeto é destinado a usuários que concluíram a Unidade 4 do curso Noções básicas do Android no Kotlin.

O que você vai criar

  • Você vai implementar o uso de rede em um app com a Retrofit e a Moshi, além do processamento de erros adequado.

Pré-requisitos

  • Um computador com o Android Studio instalado.

2. Visão geral do app final

Este é o projeto: Amphibians.

Até aqui, todos os apps que você criou dependiam de dados armazenados localmente. Desta vez, você vai usar um app que exibe informações sobre diferentes espécies de anfíbios, colocando em prática seus conhecimentos sobre rede, análise JSON e modelos de visualização a fim de permitir que o app use dados da rede. O app recebe os dados de uma API personalizada para este projeto e os exibe em uma visualização de lista.

Na versão final do app, a primeira tela que o usuário vai ver exibe os nomes de cada espécie em uma visualização de reciclagem.

7697a4e0c9bb5a76.png

Ao tocar em um item da lista, a tela de detalhes vai ser exibida, incluindo o nome da espécie e uma descrição detalhada do item.

9797605a20dc68d1.png

Embora a parte da IU desse app já esteja criada para você, ao executar o projeto inicial, os dados não vão ser exibidos. Você precisa implementar a parte de conexão à rede do app e, em seguida, exibir os dados transferidos por download no layout.

3. Primeiros passos

Fazer o download do código do projeto

O nome da pasta é android-basics-kotlin-amphibians-app. Selecione essa pasta ao abrir o projeto no Android Studio.

Para encontrar o código deste codelab e abri-lo no Android Studio, faça o seguinte.

Acessar o código

  1. Clique no URL fornecido. Isso abrirá a página do GitHub referente ao projeto em um navegador.
  2. Na página do GitHub do projeto, clique no botão Code, que vai mostrar uma caixa de diálogo.

5b0a76c50478a73f.png

  1. Na caixa de diálogo, clique no botão Download ZIP para salvar o projeto no seu computador. Aguarde a conclusão do download.
  2. Localize o arquivo no computador, que provavelmente está na pasta Downloads.
  3. Clique duas vezes para descompactar o arquivo ZIP. Isso criará uma nova pasta com os arquivos do projeto.

Abrir o projeto no Android Studio

  1. Inicie o Android Studio.
  2. Na janela Welcome to Android Studio, clique em Open an existing Android Studio project.

36cc44fcf0f89a1d.png

Observação: caso o Android Studio já esteja aberto, selecione a opção File > New > Import Project.

21f3eec988dcfbe9.png

  1. Na caixa de diálogo Import Project, vá até a pasta do projeto descompactada, que provavelmente está na pasta Downloads.
  2. Clique duas vezes nessa pasta do projeto.
  3. Aguarde o Android Studio abrir o projeto.
  4. Clique no botão Run 11c34fc5e516fb1c.png para criar e executar o app. Confira se ele é compilado da forma esperada.
  5. Procure os arquivos do projeto na janela de ferramentas Project para ver como o app está configurado.

Implementar o serviço da API

Como em projetos anteriores, a maior parte do app já foi implementada para você. Você só precisa implementar a parte de rede usando o que aprendeu na Unidade 4. Analise o código inicial. Você provavelmente se lembra da maioria dos conceitos, que foram abordados nas unidades 1 a 3. As etapas abaixo chamam partes específicas do código, quando necessário, para concluir cada etapa.

O app exibe uma lista de dados de anfíbios da rede. Os dados sobre anfíbios são originados de um objeto JSON retornado pela API. Observe o arquivo Amphibian.kt no pacote network. Essa classe modela um único objeto "amphibian" (anfíbio), que vai gerar uma lista a ser retornada da API. Cada anfíbio tem três propriedades: um nome, um tipo e uma descrição.

data class Amphibian(
    val name: String,
    val type: String,
    val description: String
)

O back-end dessa API é bem simples. Existem duas informações importantes de acesso aos dados de anfíbios: um URL base e um ponto de endpoint para acessar a lista de anfíbios.

  1. URL base: https://developer.android.com/courses/pathways/android-basics-kotlin-unit-4-pathway-2/
  2. Solicitação GET da lista de anfíbios: android-basics-kotlin-unit-4-pathway-2-project-api.json

O projeto já inclui as dependências da Retrofit e da Moshi. No pacote network, você pode ver o arquivo AmphibianApiService.kt. O arquivo contém vários comentários TODO. Execute as cinco tarefas abaixo para implementar o app Amphibians:

  1. Crie uma variável para armazenar o URL base da API.
  2. Crie o objeto Moshi com a fábrica do adaptador Kotlin que a Retrofit vai usar para analisar o JSON.
  3. Crie uma instância da Retrofit usando o conversor da Moshi.
  4. Implemente a interface AmphibianApiService com uma função suspend para cada método de API. Neste app, há apenas um método de solicitação GET da lista de anfíbios.
  5. Crie um objeto AmphibianApi para expor um serviço de inicialização lenta da Retrofit, que usa a interface AmphibianApiService.

Implementar o ViewModel

Depois que a API for implementada, você vai enviar a solicitação para a API do app Amphibians e vai armazenar todos os valores que precisam ser exibidos. Isso precisa ser feito na classe AmphibianViewModel.kt, que se encontra no pacote ui.

Observe que, acima da declaração de classe, há uma enumeração com o nome AmphibianApiStatus.

enum class AmphibianApiStatus {LOADING, ERROR, DONE}

Os três valores possíveis, LOADING, ERROR e DONE, são usados para mostrar o status da solicitação ao usuário.

Na própria classe AmphibianViewModel.kt, você precisará implementar algumas variáveis LiveData, uma função a fim de interagir com a API e uma função para processar a configuração de anfíbios na tela de detalhes.

  1. Adicione um _status a uma variável privada MutableLiveData que possa armazenar uma enumeração AmphibianApiStatus e a propriedade de apoio status para o status.
  2. Adicione uma variável amphibians e uma propriedade de apoio particular _amphibians para a lista de anfíbios, do tipo List<Amphibian>.
  3. Adicione uma variável _amphibian, do tipo MutableLiveData<Amphibian>, e a propriedade de apoio amphibian para o objeto do anfíbio selecionado, do tipo LiveData<Amphibian>. Essa variável vai ser usada para armazenar o anfíbio selecionado, que é exibido na tela de detalhes.
  4. Defina uma função com o nome getAmphibianList(). Inicie uma corrotina usando o ViewModelScope dentro da corrotina a fim de executar uma solicitação GET para fazer o download dos dados de anfíbios chamando o método getAmphibians() do serviço da Retrofit. É necessário usar try e catch para gerenciar os erros corretamente. Antes de enviar a solicitação, defina o valor do _status como AmphibianApiStatus.LOADING. Uma solicitação correta precisa definir _amphibians como a lista de anfíbios do servidor e definir o _status como AmphibianApiStatus.DONE. Caso ocorra um erro, _amphibians precisa ser definido como uma lista vazia e o _status precisa ser definido como AmphibianApiStatus.ERROR.
  5. Implemente o método onAmphibianClicked() para configurar a propriedade _amphibian definida para o argumento do anfíbio transmitido à função. Esse método já é chamado quando um anfíbio é selecionado, para que seja exibido na tela de detalhes.

Atualizar a IU do ViewModel

Depois de implementar o ViewModel, falta só editar as classes de fragmentos e os arquivos de layout para usar as vinculações de dados.

  1. A referência ao ViewModel já é feita no AmphibianListFragment. No método onCreateView(), depois que o layout for inflado, basta chamar o método getAmphibianList() do ViewModel.
  2. No fragment_amphibian_list.xml, as tags <data> das variáveis de vinculação de dados já foram adicionadas aos arquivos de layout. Você só precisa implementar os comentários anotados com "TODO" para que a IU seja atualizada com base no modelo de visualização. Defina as vinculações adequadas para listData e o apiStatus.
  3. No fragment_amphibian_detail.xml, implemente os comentários marcados com "TODO" a fim de definir as propriedades de texto adequadas para o nome e a descrição do anfíbio.

4. Instruções sobre testes

Como executar os testes

Para executar os testes, escolha uma das opções a seguir.

Para um único caso de teste, abra uma classe de caso de teste e clique na seta verde à esquerda da declaração da classe. Em seguida, selecione a opção "Run" no menu. Isso executará todos os testes do caso.

a32317d35c77142b.png

Na maioria das vezes, convém executar apenas um teste, por exemplo, se apenas um teste for reprovado e os outros forem aprovados. Você pode executar um único teste da mesma forma que faria com todo o caso de teste. Use a seta verde e selecione a opção Run.

ac6244434cfafb60.png

Se você tiver vários casos de teste, também poderá executar todo o conjunto de testes. Assim como na execução do app, você encontra essa opção no menu Run.

7a925c5e196725bb.png

O Android Studio usará como padrão o último destino que você executou (app, destinos de teste etc.). Portanto, se o menu ainda exibir Run > Run 'app', você poderá executar o destino de teste selecionando Run > Run.

ee1e227446c536fe.png

Em seguida, escolha o destino do teste no menu pop-up.

d570c947769db65c.png

Os resultados da execução dos testes serão exibidos na guia Run. No painel à esquerda, você verá uma lista de testes reprovados, se houver algum. Os testes reprovados são marcados com um ponto de exclamação vermelho ao lado do nome da função. Os testes aprovados são marcados com uma marca de seleção verde.

6d68f2bf589501ae.png

Se um teste for reprovado, o texto do resultado fornecerá informações para ajudar você a corrigir o problema.

92f3c8219c03651d.png

Por exemplo, na mensagem de erro acima, o teste verifica se um TextView está usando um recurso de string específico. No entanto, o teste é reprovado. O texto após "Expected" (esperado) e "Got" (recebido) não coincide, ou seja, o valor esperado para o teste não corresponde ao valor do app em execução. Nesse exemplo, a string usada na TextView não é squeeze_count, como esperado pelo teste.