Testing

This page is dedicated to testing the AS4 message exchange. Internally in phase4, a lot of configurations are already automatically tested based on unit tests and integration tests, but of course this is different from testing with a real remote system. This page tries to give potential ways of testing phase4, especially related to known and supported networks like Peppol.

Testing for Peppol

Testing without an official Peppol certificate

This section is written solely for developers that want to test phase4 before onboarding with OpenPeppol. Not everything can be tested without an official Peppol certificate.

The following things cannot be done without an official Peppol AP certificate:

• Send messages to an existing Peppol Service Provider (that uses a Peppol certificate)
• Receiving messages from an existing Peppol Service Provider (that uses a Peppol certificate)
• The usage of the SMP service is limited - out of scope for this project

What needs to be done for testing with two instances of phase4:

1. Create two new self-signed certificate pairs (calling them cert1 and cert2)
2. Create one new key store (JKS or PKCS12) that only contains cert1. Use the alias cert1 for it. The key store is called ks1.
3. Create another new key store (JKS or PKCS12) that only contains cert2. Use the alias cert2 for it. The key store is called ks2.
4. Create a new trust store (JKS or PKCS12) that contains only the public parts (!) of cert1 and cert2. The public parts can be extracted from cert1 and cert2 as so called PEM files. They can be identified as text files that start with -----BEGIN CERTIFICATE----- and end with -----END CERTIFICATE-----.
5. Configure the first instance of phase4 with ks1 and the trust store (both in file application.properties)
6. Configure the second instance of phase4 with ks2 and the trust store (both in file application.properties)
7. Try sending from first phase4 instance to second phase4 instance
   • When using Phase4PeppolSender.Builder as the sender, make sure to use .receiverEndpointDetails(X509Certificate, String) to provide the public AP certificate as well as the AP endpoint URL of the receiver.

The tool of choice to create the key stores and trust stores is KeyStore Explorer - it's open source and runs on all major platforms.

Note: A trust store is technically also a key store, with the convention to only contain public (=sharable) certificates and no private keys.

Testing locally (without an SMP)

This chapter describes, how you can setup a local test system and send something to yourself. This might be a good step to familiarize yourself with the components.

• Prerequisites:
  • You have checked out the latest version of phase4 locally on your system
  • You have a Peppol AP Test certificate available
• The server part for receiving message is the phase4-peppol-server-webapp module
  • Modify the file src/main/resources/application.properties according to the rules in Configuration
    • You need to configure your Peppol AP Test certificate in there
    • Make sure the property smp.url is NOT set or commented out. Otherwise receiver checks are enabled which will reject your message. You may check that the logging entry "Peppol receiver checks are disabled" is present on startup.
  • Start the server locally, by running the Java application src/test/java/com.helger.phase4.peppol.server.standalone.RunInJettyPHASE4PEPPOL. This will spawn a local Jetty at port 8080. Please check the logs to see if startup worked. If not, fix the errors :)
    • Hint for all IntelliJ IDE users: the start directory should be the projects directory (the directory that contains pom.xml). IntelliJ might use src as the default working directory. Please change this.
• To send a message to your local server, you need to have a client. An example client can be found in the module phase4-peppol-client in the class src/test/java/com.helger.phase4.peppol.MainPhase4PeppolSenderLocalHost8080.
  • It tries to send the test eInvoice read from file src/test/resources/examples/base-example.xml to the local receiver.
  • This application does not perform an SMP lookup, so it is ideal for local testing
  • Before you run it, make sure to change the certificate used in the builders receiverEndpointDetails method, to be the public part of your Peppol AP Test Certificate
    • This is the certificate the message gets encrypted with. By default this is my personal certificate. As long as you don't have my private key, you will not be able to decrypt messages and therefore you will receive an error
    • To access your public Peppol AP Test Certificate try this: open your keystore in KeyStore Explorer. Double click the matching key. In the dialog that appears, click the "PEM" button. This is your public AP Certificate part, that you can paste into this field. It should start with -----BEGIN CERTIFICATE----- (followed by a new newline) and end with -----END CERTIFICATE----- (with a preceding newline).
  • This is a Java main application, so you can just "run" it. If everything worked, you should see Peppol send result: SUCCESS

Testing within an application server (without an SMP)

Assuming you successfully ran the previous local test (without an SMP) it's just a few steps to move this onto a server:

• Build the binary version of the phase4-peppol-server-webapp web application (or use a binary version from https://repo1.maven.org/maven2/com/helger/phase4/phase4-peppol-server-webapp/)
• Deploy that on an existing application server
  • Make sure the configuration file can be found. See Configuration for details.
  • If the configuration property phase4.endpoint.address is defined, change it to the new "remote URL" (as in https://yopurserver.example.com/as4).
• If the start of the phase application was successful, go and try sending to it
  • Edit the MainPhase4PeppolSenderLocalHost8080 application from the local testing and change the receiving URL from http://localhost:8080/as4 to your servers domain

Peppol Testbed

To onboard Peppol, you need to pass the Peppol Testbed once. Currently the Peppol Testbed includes sending and receiving of messages. To use the Peppol Testbed you must have a Peppol Test AP certificate. This will not work with a self-signed certificate Ensure to have read the official Testbed - eDelivery test suite environment description and Testbed - eDelivery test suite user guide before continuing here.

To fulfill the requirements of the Peppol Testbed, you need to be familiar with the following aspects of the Peppol components.

• When receiving a message from the Testbed
  • You need to provide a receiving Peppol AS4 solution, even if you plan to only send (and not receive) messages in production.
  • You don't need to setup an SMP, because you pass the endpoint address directly in the browser UI and your Peppol Test AP certificate was already provided as a client certificate by the browser. With these two elements, the Testbed knows how to send to you.
• When sending a message to the Testbed
  • You need to perform an SMP client lookup on your side. See e.g. https://github.com/phax/peppol-commons#peppol-smp-client for how to do that. When using the phase4-peppol-client module, this functionality is already provided. If you want to know what an SMP is, read e.g. at https://github.com/phax/phoss-smp/wiki With the data received from the SMP lookup, you need to modify your AS4 parameter and include the "Endpoint Address" (=the Access Point URL) and the "Receiver Certificate" (the receivers public AP certificate) into them.
  • Once the "Endpoint address" and the "Receiver Certificate" are known, you can send the message to the Testbed.